docs: restructure the README for scanning

[lintdeveloper]

Documentation only — no code, no API change.

The problem, measured

before:  437 lines, 16 sections, no table of contents, 69% prose

Format for display began around line 250, so a reader asking "how do I format a phone number" scrolled past 107 lines of identifier-specific caveats to reach it. The two largest sections — Redact (75) and NUBAN (65) — were a third of the file and dominated by why we don't do things.

The irony: the qualities the README was optimised for — stating every limit plainly, never overclaiming — are exactly what made it unscannable. Every honest caveat was a paragraph, and the paragraphs accumulated.

Four changes

1. A capability table up front. All 14 identifiers against their is* / format* / generate* / detect() name and whether redaction covers them by default. This is what most readers actually want, and it replaces a lot of scattered prose. Generated from the real exports rather than from memory:

is*: 14   parse*: 14   format*: 14   generate*: 14
DEFAULT redact: phone vnin rsa-pin driver-license plate fixed-line
OPT-IN  redact: passport tin cac nin-or-bvn tax-id nuban voter-vin

2. Reordered so the library's shape comes first — Install → table → Quick start → Format → Generate → Mask → Redact → identifier notes → integrations. Identifier caveats no longer sit between a reader and the core API.

3. A table of contents, with all 10 anchors verified against the actual headings (0 broken).

4. 109 lines of deep reasoning moved into four collapsed <details> blocks: why validators cannot be detectors, the redaction false-positive measurements, the NUBAN residue proof behind inferBanks, the voter-VIN evidence table, and the fixed-line letter guard. Nothing is deleted — it's one click away instead of in the scroll path.

Verification

17 TypeScript snippets extracted and compiled  ✓ exit 0
10 TOC anchors resolved against headings       ✓ 0 broken
4 <details> blocks, open/close balanced        ✓
blank line after every </summary>              ✓ (markdown needs it to render inside)
lint                                           ✓

Two judgment calls

Kept the reasoning in the README rather than splitting it into docs/. A separate file would give cleaner source, but docs/ is not published in this repo, so the links would rot and the reasoning would become unreachable for anyone reading on npm or GitHub. Collapsed <details> solves the actual problem — rendered scannability — without that risk.

Source length barely moved: 437 → 416. I predicted ~260 and did not hit it. The win is in structure and rendered length (~307 lines with the details collapsed, a 30% reduction), not raw file size. Worth being straight about, since the headline number looks like little changed.

Changeset is patch.