How KAP is documented
The orientation page. Two minutes here saves reading the wrong thing for twenty.
KAP’s documentation is deliberately two layers, and knowing which one you want is most of the navigation problem.
| Facts | Narrative | |
|---|---|---|
| Answers | What is true? — paths, counts, names, rules | Why is it this way? — trade-offs, worked examples, what was rejected |
| Where | the Knowledge section | the handbook chapters |
| Length | ~50 lines a page | as long as the argument needs |
| Written by | hand, then rendered here automatically | hand |
A fact lives in exactly one place. A chapter that needs “there are ~50 UI primitives” links to the Knowledge page rather than typing the number, because a typed number is the thing that goes stale.
Anything under Knowledge, plus the pages marked generated below, is rendered from a source elsewhere in the repository and fails CI if edited here. The page itself always names its source. Edit that, and regenerate.
The three surfaces
Frontend — the web application
Start: Component Library — why the component hierarchy is shaped the way it is, and when to promote a component up it.
Then, by what you need:
- Knowledge → Component library (generated) — the placement rules, the barrel rule, and the paths.
- Storybook — every component’s props table and states, generated from the TypeScript types. Published alongside this site.
- Workspaces and Workspace Modules — the shell the components sit in.
The rule worth knowing before you write a component: anything exported from a public barrel must show what its type declares — every cva variant, every boolean prop it owns. CI enforces it.
APIs — the backend
Start: Backend API — the shape of the surface, how it is specified, and how the spec stays true.
Then:
- API Conventions (generated) — CONTRACT-API-002: what “uniform” means across two implementation languages, with the measured conformance of each rule.
- Resource design sheets (generated) — per resource family: lifecycle, idempotency, the access case, and what was rejected. Written before the handlers.
- Knowledge → Backend API (generated) — counts, the auth split, and where everything lives.
- AG-UI Contract (generated) — the event contract between the AI backend and the frontend. Normative.
The distinction that catches people: the spec says what shape a request is; the design sheet says what the resource is and what happens on the second identical call. A schema cannot carry the second.
AI assistants — the engines
Start: Engine charters (generated) — what each engine is for, who talks to it, and what it must never do. Four engines exist and they are deliberately not interchangeable.
Then:
- Grounding (generated) — what the model receives, what is written down afterwards, and what leaves the building. Read this before any security conversation.
- Behaviour specification (generated) — what the assistant must do, rendered from the benchmark that enforces it. More than half of it is refusal: the product’s worst failure is a confident wrong number.
- Knowledge → Web ↔︎ AI interface (generated) — the request path, the tool catalog, and the event families.
- AG-UI Contract — the wire.
Two things that are routinely misread, both settled in Grounding: scope narrows, RLS protects — a scope failure shows you another of your own campaigns, only an RLS failure crosses a tenant. And an engine holds no credential of its own; it gets the caller’s reach and nothing wider.
If you are here to change something
| You want to change… | Edit | Not |
|---|---|---|
| A fact (a count, a path, a rule) | docs/llm-wiki/<domain>.md |
the rendered Knowledge page |
| Why something is the way it is | the handbook chapter | anything generated |
| What an engine is for | docs/ai/charters/<engine>.md |
the rendered charter page |
| What the assistant must do | a KAB task in docs/evaluation/benchmark/ |
the behaviour spec page |
| An API convention | docs/api_standards/api_conventions.md |
the rendered copy |
| A prompt | ai/src/kavai/systems/kawa/prompts/*.md |
a Python literal |
Every generated page names its source and its regeneration command at the top. If you edit the rendering instead of the source, CI tells you — that is the whole point of the arrangement.
Why it is built this way
The documentation an agent reads and the documentation a person reads used to be two hand-written copies of the same facts, and the copies drifted. Now the facts are authored once, in the form a machine can check, and the human page is generated from them. The narrative — the part a machine cannot write — stays hand-written and links to the facts rather than repeating them.
The full reasoning is in docs/proposals/20260811_documentation_audiences.md.