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

3.7 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision 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. accepted 2026-10-31 Michał Kopeć 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 0.85 0.8 2026-10-31 365 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.