Bring CLAUDE.md up to date, and prune what --help now owns

[willkg]

CLAUDE.md had gone stale, and the cause is worth naming: the README restructure (#102) added a package, exported a function, added two make targets, and introduced a generated-artifact contract — and none of it reached this file, because a docs-only branch didn't feel like it needed an architecture note. It was changing all four of those.

Not a regeneration, deliberately

The first instinct was to delete it and re-run /init. That would have produced a competent structural summary and lost every one of these:

that single missing fallback was #68 … pinned by TestErrorDoesNotDependOnTheIndex … the clamp must never exist in two copies … body.storage proves only what was stored, never what takes effect

None of which is recoverable by reading the repo — and which is the entire reason the file is worth having.

An audit first, rather than a rewrite: every file path and every cmd/*/internal/*/schema/* package reference in it still resolves. Nothing was wrong. It was incomplete.

Added

• make docs / make docs-check, in the Commands list and in the make check ordering.
• tools/gendocs in the layout list — the only thing outside cmd/internal/schema.
• A Documentation section: that the README is a 50,000-foot view and --help is the command reference; that docs/commands/ is generated and must never be hand-edited; why cmd.Root() is exported for exactly one caller; and what the drift guard is for, including why DisableAutoGenTag is set.
• The three new docs/ files.
• escapeLinkText's rule — raw sources only, never already-rendered output. This is the kind of thing that gets re-broken: the obvious "fix" is to escape inside mdLink, which turns a bold link body into a literal \*\*bold\*\*. Code review caught that exact mistake in read/export: render <ri:user> mentions readably, and republish them as mentions #91.

Removed, on one criterion

Keep what carries a because, a test name, an issue number, or a guarantee id. Drop bare behaviour statements that --help or docs/ now own.

The frontmatter-driven-publishing section was the outlier: 3501 chars mostly restating field domains and per-verb flag behaviour, written before --help became the reference. Now 2323, keeping only what neither --help nor docs/markdown_file.md records — parent being an opaque id whichever kind it names, the validate-before-write/apply-after ordering and #127's reasoning for it, L9's asymmetry and fix's tri-state nil, and the two output rules that look arbitrary and are not.

Plus 270 chars found mechanically by diffing against real --help output: search's archived-pages-and-folders, children's folder-counts-as-a-level, the find/search complement.

Why the cut is small, and why that is the right answer

I went looking for more and mostly did not find it. cmd/search/ is the largest bullet at 3300 chars and I expected a big trim; nearly every sentence carries a measurement or a warning — text ~ ranking uselessly against siteSearch, siteSearch being silently discarded as the middle clause of three, score arriving as 0.0 on every row so nothing may re-sort a result set. That length is earned, and padding the diff by cutting it would trade a real asset for a smaller number.

On keeping it accurate

What has worked is folding it into each change, not periodic regeneration — it only drifted when a branch didn't feel architectural. Two mechanical guards would make that a guarantee rather than a habit, and I have not added either:

• the path audit above is cheap enough to be a test;
• a check that every cmd/*/, internal/*/ and tools/*/ package is named in CLAUDE.md would have caught tools/gendocs on the branch that added it.

Worth a follow-up issue if you want them. Docs only — make check passes.