74 lines
3.7 KiB
Markdown
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.
|