--- type: decision tldr: A root ABOUT.md, written by the KB's owner, states what the KB holds — purpose, audience, scope, owners, sensitivity — and the README links to it; agents read it and never edit it, ingest checks material against its scope, the MCP server serves it, and wiki/overview.md stays the agent's summary of what the KB actually holds. status: accepted decided_on: 2026-10-31 decided_by: Michał Kopeć affects: ABOUT.md, AGENTS.md, README.md, wiki/overview.md, .agents/skills/ckb-ingest/, .agents/skills/ckb-init/, .agents/skills/ckb-upgrade/, .agents/skills/ckb-reset/, .agents/modules/mcp/server/, docs/MANUAL.md confidence: 0.85 quality: 0.8 last_updated: 2026-10-31 freshness_window_days: 365 retention: high --- # D-0010 — `ABOUT.md` states what a KB holds, and the README links to it **Status:** Accepted · **Decided:** 2026-10-31 · **Deciders:** Michał Kopeć ## Context Every KB's `README.md` is the template's own technical README, and `ckb-upgrade` overwrites it. It describes the Cascade KB tooling, which is the same everywhere. Nothing a reader opens first said what *this* KB is about, who it is for, or who to ask. `wiki/overview.md` comes close, but `ckb-ingest` writes it from what was ingested. It describes what the KB holds, not what it is meant to hold, and a person who corrects it competes with the next ingest. Intent, scope and handling rules are the owner's to state, and the agent should read them. ## Decision 1. **A root `ABOUT.md` is the owner's statement of what the KB is for.** Sections: Purpose, Audience, Scope (in and out), Owners and contacts, Expected sources, Sensitivity, Language and terms. Each ships as an HTML comment saying what to write. `type: about` frontmatter carries a `tldr` and `last_updated`. 2. **It is the user's file.** Agents read it and edit it only when asked. It is not a cascade layer and not part of the template layer: `ckb-upgrade` creates it only when missing and never diffs it, and `ckb-reset` never touches it. `ckb-init` copies the scaffold and asks one optional question to fill Purpose and `tldr`. 3. **The README links to it at a fixed path.** Because the README is overwritten on upgrade, the link has to be generic; it sits right under the source-repo pointer in both languages. 4. **Agents use it.** `ckb-ingest` names material outside its Scope or ruled out by its Sensitivity section and ingests it only on the user's say-so. Questions about the KB itself are answered from it before `wiki/overview.md`. The MCP server puts it first in `kb_overview` and takes its `tldr` as the KB's description, ignoring the scaffold's placeholder. 5. **`wiki/overview.md` keeps its role** as the agent's summary of what the KB actually holds, and links to `ABOUT.md`. ## Alternatives considered - **Link the README to `wiki/overview.md` only** was rejected: an agent-maintained page cannot carry the owner's intent, scope limits or handling rules, and regeneration would compete with hand edits. - **Replace `wiki/overview.md` with `ABOUT.md`** was rejected: the summary of what has been ingested is still useful and is read by the exporters, `ckb-quiz` and the MCP server; moving it touches every one of them for no gain. - **Put the owner's statement in `ckb.yaml`** was rejected: it is prose for people, and YAML is configuration. ## Consequences - No `kb_schema_version` change: `ABOUT.md` is outside `wiki/`, like `templates/` (D-0008). - An unfilled `ABOUT.md` is harmless: ingest skips the scope check and the MCP server falls back to the overview's `tldr`. - Scope enforcement is only as good as what the owner writes. Ingest reports conflicts; it does not decide them.