Wiki Schema
How does an LLM-maintained wiki keep its maps true enough to compound?
A well-structured wiki serves humans who need to learn and AI agents that need to reason. The control plane — schema, indexes, templates, generated maps, and routing rules — must be more accurate and more compressed than ordinary content. If the map lies, every later agent wastes thought.
For naming decisions, start at Naming Standards. It is the System of Names front door that maps each name class to the authority that owns it.
For organization decisions, Naming Standards leads before page typing or reader navigation. It decides the kind of thing, the authority, the placement axis, and the migration proof. Page Types then chooses the page job; Folder Ownership mirrors capability ownership; information architecture improves discoverability after the taxonomy is stable.
Control Plane
These files define what exists. Keep them succinctly incompressible: only truth, route, owner, and next action.
| Layer | Authority | Rule |
|---|---|---|
| Raw sources | Immutable evidence | Preserve source material; do not rewrite it as wiki truth |
| Public wiki | Compiled knowledge | Teach reusable patterns that stand without private context |
| Schema and indexes | Navigation contract | Define page jobs, routes, and read order; never carry stale aliases |
| Templates | Implementation standard | Tell agents exactly how to produce one artifact class |
| Generated projections | Derived map | Regenerate from source; do not hand-author as truth |
| Private state | Operating system | Keep plans, demand, traces, and delivery status out of public docs |
Primary Subjects
Primary subjects are the public front doors. They classify the main thing being studied. Page type then names the job the page performs.
| Subject | Route | Owns |
|---|---|---|
| AI | /playbook/ai/ | Models, agents, instruments, work charts, inference, evals, and directed cognition |
| Applications | /playbook/applications/ | Software selection, function specs, buy/build decisions, and vertical application patterns |
| Business | /playbook/business/ | Capability domains, value flows, operations, customers, instruments, and business models |
| Hardware | /playbook/hardware/ | Devices, local compute, phones, blockchain nodes, IoT sensors, DePIN hardware, and edge machines |
| Industries | /playbook/industries/ | Market maps, players, control points, 5P views, and opportunity surfaces |
| Software | /playbook/software/ | Engineering practice, software architecture, developer tools, and software platform systems |
| Governance | /playbook/governance/ | Law, regulation, rule systems, network states, and institutional decision design |
| Science | /playbook/science/ | Natural-world principles, scientific method, matter, biology, physics, and evidence frames |
| Systems | /playbook/systems/ | Feedback loops, diagrams, matrix thinking, improvement, and process methods |
| Standards/Wiki | /playbook/standards/, /playbook/wiki/ | The operating control plane: names, templates, quality gates, page jobs, and schema |
Hardware is the primary subject when the artifact is a physical device or machine position that makes software more useful: it captures data, runs models, signs transactions, stores state, transmits signals, proves work, or acts in the world. Keep platform as the 5P pillar inside business and industry pages. Do not recreate top-level /playbook/platform.
The cognitive spine is attention. Intention chooses direction. The story of that choice belongs at /intention; reusable mechanics belong in /playbook. AI belongs under /playbook/ai/ because artificial intelligence is a technology for weighting context, relating signals, predicting outcomes, and delegating cognition.
Design Constraint Spine
Four constraints govern every structural decision in this control plane: ontology, epistemology, taxonomy, and axiology. They are not separate systems — they are four legs of one frame. Remove one and the system drifts in a predictable direction.
For the naming application of this frame, use Naming Standards. Wiki Schema names the control-plane constraint; Naming Standards turns it into the System of Names for folders, files, routes, terms, skills, commands, generated projections, and business knowledge placement.
Ontology — what exists: AISL/DDL nomenclature and DML symbols define the typed state space of entities, states, and relationships agents can perceive and act on. If something is not in the ontology, the system cannot name it, route it, or reason about it. The canonical agent knowledge contract lives at Agent Knowledge Contract. Structured language data used by generators lives under src/data/agent-language.
Epistemology — how truth updates: the trust architecture, Map-First Edit contract, receipts, capability mirror, and Receipt/Freshness/Arbitration laws.
The wiki log (.EVOLVE/wiki-log.md) is the epistemology layer: a claim with no entry there has no verified truth-state. Rich ontology with weak epistemology produces hallucination. The system knows what things are named, but it cannot verify whether those names are current.
Taxonomy — how entities sort: the playbook folder tree, folder-as-function convention, naming standards, and flow-routing's four-question placement rules. Taxonomy makes navigation reliable. Mixed taxonomy lets two pages claim the same territory, and neither can be trusted as the primary source.
Axiology — what matters: the 5P card Performance-first, kill signals, priorities, and the what-next loop. Axiology names the optimization target. Without it, the system cannot distinguish improvements that matter from improvements that are merely possible.
Map-First Edit Contract
Every /playbook content edit starts by reading the wiki control plane, not by opening the page cold.
The required loop is:
- Start at the Wiki Control Plane hub, then read Wiki Schema, Naming Standards, Wiki Index, Page Types, and the Agent Knowledge Contract.
- Choose the route, name class, page type, template, destination, and change class before editing. Use Naming Standards when the change organizes a folder tree, renames a route, names a file, changes a business knowledge category, or touches a term, symbol, skill, generated projection, or private-state reference.
- Record a preflight receipt with
scripts/guards/wiki-flow-guard.mjs preflight --target <docs-path> --change-class <maintenance|content|new-page|rewrite>. - Edit the docs page.
- Close the receipt into
.EVOLVE/wiki-log.md, includinglanguage_update: updatedorlanguage_update: not-applicablewith a reason.
This is the Map-First Edit discipline: the map decides the page job before prose changes. The Wiki Control Plane is the schema, index, page-type map, DDL, and DML read together as one routing surface.
Maintenance changes may be small, but they still need a preflight reason. New pages and material rewrites must declare type and template before the first edit. If a docs edit creates or sharpens shared language, update the DDL/DML surfaces in the same close loop.
Agent Read Order
This order is binding before any /playbook edit. A docs job starts from the maps, then the target page. The front door is the Wiki Control Plane hub.
- Read this Wiki Schema.
- Read Naming Standards when the task touches folder structure, route names, filenames, page categories, skill names, business knowledge placement, generated projections, or canonical terms.
- Read the Wiki Index.
- Read Page Types.
- Read the Agent Knowledge Contract before changing agent-facing language, capability, discovery, execution, or proof surfaces.
- Read Glossary when the change touches public vocabulary.
- Read the relevant domain or playbook.
- Record a Map-First Edit preflight before changing
/playbook. - Use the project CLI only when the task needs private/project state.
Routing Rules
Where does a piece of knowledge belong? First decide who it serves and what job it does.
| Content class | System class | Rule |
|---|---|---|
| Public reusable know-how | Public docs | Explain it so any human or agent can reuse it without context about your specific situation |
| Public argument or narrative | src/pages or /rhetoric story surface | Use when the job is persuasion, timing, or story — not explanation |
| Canonical language | Language layer | Terms and compressed agent notation live here; public docs link to it, not the reverse |
| Private plans and delivery state | Private project system (CLI or database) | Keep project-specific demand, decisions, delivery traces, and status out of public docs |
| Raw or unresolved ideas | Staging area | Process toward docs, language layer, demand, or deletion — do not publish until resolved |
| Engineering implementation | Build system | Product and platform changes belong in the engineering codebase, not the knowledge base |
Routing test: read the content aloud to someone who has never seen this repo. If it teaches a reusable pattern, publish it in /playbook. If it sells why the Dream matters or frames the journey, publish it in src/pages. If it describes project state, keep it private.
Page Types
Every page has one job. Name it before writing.
| Type | Job | Required shape |
|---|---|---|
hub | Orient a section — route, never teach | One-sentence mantra, ranked Spine (every child, scented), Zoom Out. Body ≤ ~30 lines. Template: Hub Index Template. All index rewrites follow the Index Page Standard |
concept | Explain one reusable idea | Definition, why it matters, when to use, links |
playbook | Guide repeatable action | Trigger, steps, outputs, checks |
domain-map | Explain a territory | Value chain, players, forces, useful questions |
evidence | Preserve source-backed claims | Claim, source trail, confidence, implication |
glossary | Clarify language | Canonical term, aliases, contrast, language-layer link |
decision-record | Explain a public architectural decision | Context, decision, consequences, date |
Diátaxis underlies this: tutorials teach, how-to guides direct, explanations clarify, references describe. These page types adapt that discipline for a wiki read by people and agents.
Frontmatter
New or materially revised docs should include:
---
title: Clear Title
sidebar_label: Short Label
description: "One sentence that explains the page job."
type: concept
loop_phase: intention
level: working
tags:
- Relevant Topic
---
description is the answer-engine summary. Search engines and AI agents both read it before reading the page. Write it as a direct answer to the question the page solves.
title should be human-readable. Avoid internal shorthand unless the page defines it.
sidebar_label should be shorter than the title when the title runs long.
type names the page job: hub, concept, playbook, domain-map, evidence, glossary, or decision-record.
loop_phase names the primary reader intent: intention, action, or evolution.
level controls projection depth: entry for front doors, working for useful second-level pages, and deep for long-tail reference.
Source Rules
External claims need a Sources, Links, Context, or Source Trail section. Label interpretation as interpretation — do not present it as raw evidence.
Private context may inform a page, but the page must stand alone. Do not expose private project state, client names, or internal system paths as reader-facing provenance. The reader should not need internal process details to trust what is on the page.
Staging paths may be named only when the page's subject is the operating system itself. Everywhere else, describe the pattern without exposing internal plumbing.
Agent Maintenance Operations
An LLM-maintained wiki stays alive through four recurring operations. Any agent working the knowledge base should know all four.
| Operation | Purpose | Output |
|---|---|---|
ingest | Turn raw signal into durable knowledge | A public doc, a canonical term, a demand trace, or deletion |
query | Answer from durable sources first | Cite public docs; use private project systems only for project-specific state |
lint | Detect drift and broken structure | Findings for broken links, orphan pages, language drift, and source gaps |
promote | Preserve reusable answers | A public doc, a canonical term, a compressed notation token, or a project trace |
The loop: ingest raw signal → query what exists → lint for drift → promote what is reusable.
Language Alignment
When a concept becomes reusable, it earns an entry in the canonical-term glossary. When agents need it in compact form, it earns a notation token.
Naming Standards classifies which language authority owns the name. DDL owns canonical terms. DML owns compact notation. This page owns the edit route, not the term definition.
The sequence:
- Add or sharpen the canonical term in the language layer.
- Add a public docs home if the concept needs explanation.
- Add a compressed notation token only if agents need it in a compact form.
- Keep language-layer links pointing at live public docs — never at staging paths or private systems.
A term that lives only in conversation is not yet canonical. A term that lives in the language layer and links to an explanation page is ready to compound.
Smart Connections
Links are part of the schema. A useful link tells the reader why to move, not only where to click.
Use typed Context links for important relationships:
- depends-on — this page needs that concept first.
- applies-to — this method operates in that domain.
- instance-of — this page is a concrete example of that pattern.
- contrasts-with — this page is clearer against that foil.
- pairs-with — these pages naturally co-activate.
- proved-by — that page measures or validates this claim.
- risk-governed-by — that page contains the governance, legal, safety, or trust constraint.
Use kb-smart-links for relationship quality. Use code-fix-links for broken, relative, or empty URLs.
Failure Modes
- False map — the index or schema says a page has one job, but the body performs another.
- Mixed axis — one folder classifies by method, domain, lifecycle, and audience at the same time.
- Stale projection — generated maps lag behind frontmatter changes.
- Private dependency — a public page needs internal project state to make sense.
Context
- Wiki Index — full map of what is here and why
- Page Types — projection of pages by job
- Index Page Standard — how index pages route before they teach
- Purpose — why the wiki exists before any page job.
- Principles — truths that decide whether a page belongs.
- Platform — where generated maps and tooling become operational substrate.
- Performance — how stale routes, failed checks, and retrieval quality are measured.
Questions
How does the structure of your knowledge base reflect what you actually believe is worth knowing?
- Which pages in your wiki were written to teach a pattern — and which were written to document what you did?
- Where does the routing decision ("public docs vs private project system") get made, and by whom?
- If an AI agent queried your knowledge base cold, which pages would it trust — and why?