docs: rewrite the documentation around the reader

[mikessh]

The docs were an accurate design record written in the voice of one. This turns them into documentation: task-oriented, rationale separated from instruction, and with the pages a new user needs first actually present.

What was wrong

Voice, and it was systematic rather than occasional:

Artifact	Where
Never: — a CLAUDE.md agent-instruction marker, meaningless to a reader	6 docs pages, README, and 21 user-facing CLI --help strings
⛔ / ⚠ / ✅ as severity markers, where Sphinx has admonitions	21 in README, 13 across 5 pages
Self-referential postmortem ("the mistake this project made and had to retract")	shm, installation, usage, README
Editorialising about candour ("the honest statement of…")	6 places
A local absolute path on a public site, plus an internal hostname	landing page, usage

Structure — the pages a new reader needs first did not exist. No quickstart (the entry point was installation, opening on scikit-build-core's CMake caching). No CLI reference for 22 commands. No output reference, so "what is in clones.tsv" was spread across six pages. No glossary. Benchmarks in four places in three framings, including a stage-vs-stage table CLAUDE.md itself warns is "a retraction waiting to happen". README at 999 lines was a second copy of the site.

What changed

Six new pages. quickstart (runs the committed 660-pair fixture end to end, every number is that run's real output), cli (all 22 commands by task), outputs (every file, every column), glossary, how_it_works, benchmarks.

benchmarks is the single home for measured figures. Nothing dropped — all 118 distinctive figures from the old README are accounted for in the new README plus docs, including the fine-grained V-coverage stratifications that previously existed only in usage. usage goes 847 → 627 lines by linking rather than duplicating.

README 999 → 198 lines. What arda is, install, quick start, why, a link table.

cli.py: Never: removed from all 21 help strings and docstrings. Code comments keep it — that convention stays.

Left alone deliberately: skills/arda/references/*.md (23), src/arda comments (111), integrations comments (8) — agent- and developer-facing, not reader-facing docs.

Verification

• sphinx-build -W --keep-going → zero warnings, in a clean env matching the docs CI job (sphinx + theme + polars + seqtree, no arda installed).
• Every arda command and flag written into the new pages introspected against the live CLI — the failure class CLAUDE.md calls out. No unknown command or flag.
• Every distinctive numeric figure in the old README checked present in the new README + docs.
• ruff check src/ clean; 1,162 unit + 100 synthetic/realworld tests pass, 9 skipped (optional olga extra).
• No behaviour change: the cli.py diff is help and docstring text only.

🤖 Generated with Claude Code