docs(readme): restructure around the pipeline, and re-measure every figure

[ojassug]

Documentation only. No source, no tests, no behaviour change — README.md and one
CHANGELOG.md entry.

What changed

The README opened with a five-paragraph experimental-Gateway warning before saying what the
tool does, and carried its own corrections inline as retractions. It is restructured to:

worked example → how it works → install → usage → measured savings → what it does not
do → reference → project state

The caveats are gathered into one named section instead of scattered, on the view that in this
project they are a feature of the documentation rather than an appendix to it.

Three Mermaid diagrams, chosen for the three things readers actually get wrong:

Diagram	What it settles
The pipeline	Three entry modes → one engine → the gate → emit / repair / fail-open
Plan selection	Why no budget flag means a guaranteed 0% (pass_through, empty stage list)
The validation gate	Measurement gate and retention gate as two gates; per-item repair; fail-open

All three were rendered before committing rather than assumed to parse — extracted from the
file, rendered through mermaid 11.15.0, checked for a real SVG: 12/6/12 nodes, 13/5/16 edges,
zero parse errors.

Two measured claims did not survive re-running them

This is the part worth reviewing, and the reason there is a CHANGELOG entry rather than a
bare "docs" line.

1. The knapsack bullet was quoting a stage metric as a result. It read "31 files in,
15 pruned, 20,540 tokens saved" for optimize ./src/core --max-input-tokens 4000. Re-run
against this commit:

pruning:topology-pruner    itemsPruned 13 · tokensSaved 17,823
compression:token-hashing  itemsHashed 19 · regionsHashed 221 · bytesSaved 121,103

fallbackUsed: true
  19 × CONSTRAINT_DIRECTIVE_LOST
  Semantic drift metric (0.42) exceeds maximum threshold (0.40)

The caller receives 0.00%. tokensSaved is what the stage computed, upstream of the gate —
invariant 10's shape, arriving in the documentation instead of the engine. Now written up
honestly under It will not save you from a comment-heavy codebase, with the fallback shown.

2. My own first draft was wrong in the same family. It claimed undeclared TypeScript over
stdin "falls back". It does not — languageSupport.noneSupported is true,
compression:token-hashing finds nothing eligible and skips the item, and fallbackUsed stays
false at a silent 0%. Caught by reading the trace rather than the token delta, before it
shipped. The section now quotes the real languageSupport.reason string.

Corrected against source

• configSchemaVersion is 1.1, not the 1.0.0 first written.
• TOKENDAMPER_PLANNER_MODE accepts pass_through only — previously undocumented.
• Python over stdin is probe-detected without --language; the old text implied otherwise. The
  gap is TypeScript, and the README now shows the 880 → 880 vs 880 → 739 measurement.
• npm latest is 1.7.2 against this repository's v1.7.3, recorded as such.

Figures now in the README, all re-run at this commit

Claim	Measured
Worked example	1,968 B → 683 B · 609 → 196 tokens · 4 regions · driftScore 0 · no fallback
--keep-docstrings	609 → 273
No budget flag	609 → 609 · pass_through · stageCount 0
TS stdin, undeclared / declared	880 → 880 / 880 → 739
12-file knapsack	8,005 → 2,669 (66.66%) · 8 pruned · plus the stderr warning
Config example	Runs clean, 609 → 367

Corpus and Go figures are cited from docs/audit-remediation-status.md §2 and DECISIONS §61
with their frozen commit named, not re-derived from memory.

Checks

• All 14 linked paths exist; 18 internal anchors resolve under GitHub's slug rules.
• Code fences balanced (56); <details> balanced.
• The README's own config example was executed, not eyeballed.
• npm test on this branch: 936 of 938 pass. The two failures are timing-sensitive and
  pre-existing on this machine — bench.test.ts hitting a 5 s timeout while shelling out to
  python, and gateway-streaming-timeout returning 504 instead of 200. The count varied
  between runs (3, then 2), which reads as flakiness on a cold Windows worktree rather than a
  regression; nothing in this PR touches src/.

Noted, not fixed (out of scope)

src/adapters/mcp/tools.ts:33 still tells MCP callers that targetReductionRatio "currently
acts as an on/off switch rather than a proportional target". DECISIONS §48 made it a binding
ceiling. One-line doc-string fix, left for a source PR.

🤖 Generated with Claude Code