Wiki Schema
An LLM-maintained wiki compounds only when its maps stay true.
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.
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 |
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.
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:
- Read Wiki Schema, Wiki Index, Page Types, DDL (
/agents/ddl-nomenclature), and DML (/agents/dreamineering-symbols). - Choose the route, page type, template, destination, and change class before editing. Use Naming Standards when the change names a route, file, 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.
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.
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
- Start Here — entry point for orienting to the knowledge base structure
- 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
- Content Standards — voice, formatting, and sourcing rules applied across all pages
- Intelligent Hyperlinks — how links carry context and sustain flow across the knowledge base
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?