ckb/docs/decisions/0010-about-file.md
Michał Kopeć da2833abfe Sync: local changes as of 2026-11-01T20:31:36Z
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 21:31:36 +01:00

74 lines
3.7 KiB
Markdown

---
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.