v1.19.0 ·
The graph knows where, not why
Forty-two instances had left forty-two folders of requirements, designs and retrospectives. Not one answered the question a person actually asks: how does this thing work?
Three places came close, and each missed. The 33 release posts are real prose, but they are grouped by tag and written as narrative, so they answer "what happened in v1.8.0", not "how does cost tracking work now". The docs site covers the framework, and nothing built with it. And the knowledge graph, which is what AI agents actually read, is terse on purpose because it competes with the task for prompt space. It records shape. It cannot afford reasons.
That last gap is measurable. The graph held 64 module entries, and 17 lines of them described a package deleted at the website cutover. aidlc knowledge context compiles those lines into CLAUDE.md, so every agent starting work here was being told about code that was not there. Nothing reported it, because a stale entry and a correct one look the same.
Missing reasons cost something too. The graph says a function returns an ok or reason result instead of null. What it has no room for is why: a null could not tell "no transcript on disk" from "transcript found, no matching turns", and a bugfix bought that distinction. An agent holding only the fact will simplify the bug back in, confidently, with a smaller diff.
What changed
I wrote a landing page and nine topic pages at the repo root, covering why each part exists, what breaks without it and how to use it. They are for two readers with the same gap: a person trying to understand the system, and an agent about to change it. The split with the graph is by question. The graph says where a thing is. The pages say why it exists.
One file declares which pages exist, what code each documents, which CLI commands each covers and which broken-looking things are deliberate. A test, packages/cli/test/docs-topics.test.ts, checks that against reality. Its 22 tests are structural only. Declared pages exist and undeclared ones do not. The three required sections are present and not empty. All 20 top-level commands are claimed. Every repo path a page names resolves.
Choices
I did not write one page per instance. A document describes the system as it is, and an instance describes one change. A bugfix later corrected what a feature built, so neither folder holds the truth. That is why nine topics, not forty-two pages.
The command check compares an exact set against a declared mapping, not a text search. A search passes on a passing mention, like a page saying "unlike aidlc doctor, this...", while documenting nothing. The exact set also catches a page still claiming a command that was removed.
I did not add a gate. Features that watch the lifecycle are a tax on every future instance, and five of six bugfixes traced back to them. The deployment skill got one checklist step instead.
What it does not fix
Prose going quietly out of date is caught by nothing, and I wrote that down as an accepted risk. The pages sit at the repo root, not in the content package, because shipping them there would put framework text into every project, a second copy that can drift. Agents in projects that only installed the package cannot see them. That gap is a backlog item with three candidate fixes priced.
The path check nearly ate itself. A page explaining the deleted package has to name its path, which fails the check that forbids unresolvable paths. The escape is an allowlist that needs a written reason, and the allowlist is itself checked, so an entry that still resolves fails as stale.