docs: a reference you can scan, and one cost figure everywhere (#475)
The last read-through before a first tagged version. Docs and code read as a consumer and as an agent
would; four files changed, and the largest change moves almost no words.
**`docs/API.md`'s `## Diagnostics` is now scannable.** Eight prose paragraphs ran 22 to 74 lines, so
looking up one field meant reading everything above it. Split at sentence boundaries and rewrapped:
the longest prose paragraph in the file goes 74 lines → 22, and the file 5,342 → 5,386 lines, all of
it line breaks.
The reflow is checked, not asserted. The split script refuses to write unless the range it read,
whitespace collapsed, is identical to the range it writes. Compared word by word against `23cc15d`,
`docs/API.md` differs in exactly two regions out of 63,425 words — the two clauses round 1 asked for,
each a paragraph opener whose subject had been one line above it: `which it was not` →
`` which `errors` was not ``, and `Bounded, which nothing else in this payload needs to be` →
`` `failures` is **bounded**, which … ``.
**One measurement, one figure.** `docs/cost.md` opened with "about 11¢ a page" while its own table
says 10.7¢, and `CONTRIBUTING.md`'s "a number instead of an adjective" rule quoted the rounded one as
its example. Both now read 10.7¢, matching `README.md` and the table the number comes from.
**`.env.example` names `GITHUB_API_BASE_URL`.** `config.example.yaml` reads it for GitHub Enterprise
and `.env.example` never mentioned it. Commented out, since unset is correct for public GitHub.
Also verified and left alone: no TODO or FIXME in `docs/`, no stale `0.1.0`, 0 broken relative links
across all 13 markdown files, and the four other long blocks a paragraph checker reports are bullet
lists.
Two review rounds, both approved, round 2 with nothing new. Gates on the merged head: typecheck clean,
1,707 tests pass, e2e ALL ENDPOINTS PASSED, anchors 440 links / 0 bad.
Refs #467
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>