Docs quality: one fact one home, and index what's read under pressure

[Sbussiso]

Yesterday's pass fixed accuracy. This is about quality — and it starts by undoing damage I did.

I made the duplication worse

ARCHITECTURE.md appeared in all eight cross-file duplication clusters. I'd restated numbers that already had homes.

The reasoning behind the agent's isolation existed in three files in three phrasings. "23 tools" appeared five ways across three files. Those are exactly the facts that drift: a number in three places gets updated in one, and then two files are quietly lying.

The rule, now recorded in docs/README.md

• Reference docs state a value once, in whichever doc owns the subject.
• ARCHITECTURE.md carries structure, not values — except facts that only make sense across services, like Fly's proxy bind budget, which is the entire reason two services sleep and one can't.
• Operational docs may inline a value where stopping to look it up would make them unusable. "kill a CameraNode for >90s" is an instruction, not a specification.
• Prefer pointing at code. A value with a good comment beside it is more durable than the same value copied into prose.

Applied, 384 MiB now appears in no document at all. It lives in fly.toml next to the comment explaining why it moves together with memory_mb — where someone changing it is already looking.

One overlap left deliberately: the agent's ~10s boot time is in both its own doc and the cross-service table. Removing it would serve the rule at the reader's expense — they'd no longer learn why their machine stays warm without following a link.

None of the four longest docs had an index

ON_CALL.md is 611 lines and describes itself as "optimised for being read under pressure." It wasn't. It opened with a tools cheatsheet — but a responder knows the symptom, not the scenario letter.

It now opens with a symptom-to-scenario table, including a row for "data is missing, corrupted, or gone" → DISASTER_RECOVERY.md, so you find out you're in the wrong document before working through procedures that can't help.

DISASTER_RECOVERY.md had the same gap plus one I created: I'd put its index at line 122, behind a long migration note. An index you have to scroll to isn't an index. Moved above the fold, and it now leads with "a restore is destructive — read the whole procedure before running its first command."

AGENTS.md gets a contents table and now points outward for the two things it was restating.

Verified

79 internal links and anchors checked, including cross-file fragments — 0 broken.

🤖 Generated with Claude Code