docs: make the documentation say what the code actually does

[guycorbaz]

An audit of every documentation surface against the shipped code, and the fixes for what it found. Fourteen findings; each one is verifiable from the repository.

Contradictions and plain falsehoods

#	Where	What was wrong
1	ROADMAP.md	The parking lot listed eleven issues as pending work — #145-#152, #202, #216, #217, #220, #389. All eleven are closed, and the same file said "the backlog is empty" two sections earlier.
2	docs/ci-cd.md	"3-gate model"; there have been four gates since story 8-8. The branch-protection procedure said to require exactly three checks — applied literally, the wizard lane never blocks a merge. audit.yml (shipped three weeks ago) and pages.yml were unmentioned, and the db-integration job still quoted the hardcoded --test X allowlist that #357 replaced with --tests.
3	docs/route-role-matrix.md	Called itself authoritative; documented 82 of 148 routes. Missing: the setup wizard, the HTTP API, the wishlist, saved searches, labels, API keys, the shelf audit, every confirmation modal, and the restore route added last week.
4	manual ch. 2 (EN + FR), src/routes/admin.rs, CLAUDE.md	"five tabs" / "cinq onglets". Six since the API-keys tab. The admin.rs module doc still described three of them as stubs for future Epic 8 stories.
5	README.md	"Locale files in locales/{en,fr}.yml". Four locales, and tests/locale_parity.rs enforces it — the exact trap that turned CI red on #478.
6	docs/dockerhub-overview.md	"All deployment-time settings are environment variables — no config file." Untrue since story 8-5: loan thresholds, session timeout, provider keys and timeouts, language, log level live in the settings table and are edited in Admin → System. The page now explains the two layers and what the env vars still do (seed a fresh deployment; inert once the setting is saved).
7	README.md	A stuttered clause, "a metadata-clarity minor: a metadata-clarity minor" — a drift symptom, removed with the paragraph that carried it.

What the documentation did not know had shipped

#	Where	What was missing
8	manual ch. 5 (EN + FR), Docker Hub, website	K10plus — in the chain since v1.16.0 and, by the project's own measurement, the leading contributor of bibliographic zones — was named nowhere but the README. Added to the provider table and to the zone-completion section, with the ISBN-prefix gating and why it exists.
9	manual ch. 3 (EN + FR)	The audit section said "mybibli does not ship a dedicated audit mode" and walked the reader through a workaround built on the search page — three releases after CR #237 shipped exactly that mode. Rewritten around what the application does: raise the flag on a volume or a whole shelf, walk /audit in location → V-code order, press Checked.
9	manual ch. 3 (EN + FR)	The valuation pages and the /labels page existed only as release-note entries in chapter 8. Both now have reference sections.
11	docs/accessibility-audit.md, Docker Hub	An audit dated 2026-05-10 presented in the present tense as covering mybibli; its thirteen surfaces have not grown since, so /labels, /wishlist, /stats/value and /audit have never been through it. The file now says so; Docker Hub's "axe-core CI gate over every reachable surface" is corrected.
12	docs/architecture.md	Titled as the architecture reference, documenting one subsystem. Renamed docs/permanent-delete-and-purge.md, with a scope line naming the two files that do hold the architecture.
13	README.md	The Documentation section never linked the user manual — which the README itself cites twice by chapter number — nor the route matrix, the UNIMARC mapping, the error-message guide, the accessibility audit, or the community-health files. Rewritten as three audiences: running it, working on it, product and planning.

Vocabulary (10)

"Labels" meant two things in one manual: the V-code/L-code stickers of chapter 2, and the management labels of v1.18.0. Chapter 2 is now spine labels, the feature is management labels throughout, and each section points at the other. No code or interface string changed.

Repetition (14)

The release history was told five times — ROADMAP's "Now" paragraph, ROADMAP's per-version sections, a README paragraph of comparable length, the website, and the manual's chapter 8 — and had already drifted (finding 7 is one symptom). ROADMAP is now the canonical copy. Its "Now" section states the current release, what sits merged-but-unreleased on main, and that the tracker is empty, instead of reciting ten releases. The README quotes the current release and points there. The website and the manual keep their own telling: different audiences, and chapter 8 is the only copy that works offline.

Two behaviours documented, not changed

Writing the route matrix surfaced this: GET /wishlist/print and GET /wishlist/export.pdf take no Session, so the printable wish list is served to anyone who knows the URL, while GET /wishlist requires Librarian. That contradicts the matrix's own standing policy ("anonymous reach covers catalog browsing and detail pages only"). Both rows are recorded with the role they actually have, and an Anomalies section says why they are documented rather than quietly fixed — changing them changes behaviour, which belongs in its own PR. Worth an issue.

Testing

• cargo clippy --all-targets -- -D warnings — clean.
• cargo test --lib — 1175 passed (two Rust doc-comments changed, nothing else in src/).
• docs/manual/build.sh en and fr — both PDFs rebuilt and committed, no undefined references.
• Every relative link in *.md and docs/*.md resolves.
• The route matrix was generated from src/routes/*.rs (route → handler → require_role / ApiKeyAuth) and the result checked by hand, including every row reading Anonymous.

🤖 Generated with Claude Code

https://claude.ai/code/session_01D5cV9QRqQAFpiNKZwZfoNX