docs(readme): the fee-reality benchmark as a terminal capture, generated from a real run (#646)

[eaitbrahim]

Closes #646 — the last deliverable. The README hook, the priced-twice table, the reproducible figures and scripts/render_fee_reality.py all shipped earlier; what was missing was the terminal capture.

One constraint decided the shape

"Generation tooling committed … so the GIF regenerates when the measurement does."

A hand-recorded screencast can't satisfy that. It's a binary blob whose numbers freeze the moment somebody hits record, and the first time the ledger moves it becomes a picture of a measurement that is no longer true — a marketing asset wearing a measurement's clothes, which is the exact thing this README argues against.

What is real, and what is not — said in the caption

render_fee_reality_cast.py runs render_fee_reality.py as a subprocess and captures its actual stdout. That command really reads docs/experiments/trials-ledger.jsonl, really parses the recorded fee curve, really prints those figures. No number is retyped and there's no fixture — a test asserts the committed asset carries the same cells the renderer emits today, and swapping the capture for a fixture kills it.

The pacing is composed. Nobody types at a uniform 55 ms per character. The README caption says so in a sentence — "The pacing is composed; the output is not" — because a capture presented as an unedited recording would be a small lie in service of a page about not telling them.

Two formats, one recording

file	why
docs/assets/fee-reality.cast	asciinema v2 — plain JSON lines a reviewer can read; any asciinema tool plays it
docs/assets/fee-reality.svg	what the README embeds: renders inline on GitHub, no player, no CDN, no JavaScript — and it's text, so a regenerated capture arrives in review as a legible diff

The SVG is hand-built rather than shelled out to agg or svg-term-cli, for the same reason the asset is generated at all: a capture produced by a toolchain this repo doesn't have can't be regenerated by someone who clones it.

Deterministic, so its diff means something

No timestamp in the cast header — that's where asciinema puts the wall clock, and with one every regeneration would be a diff even when the measurement hadn't moved. Verified byte-identical across runs.

#646's other constraints

• ✅ Every number reproducible from a recorded run — a test compares the capture against the renderer's live output
• ✅ No competitor naming — swept for five product names across both assets
• ✅ Dated caption with the per-venue fee basis in frame — Coinbase taker 1.2% · rendered from the trials ledger
• ✅ Generation tooling committed, with a check mode wired into the suite

Gates

6,300 passed / 3 skipped; ruff clean (the one E501 is pre-existing). 7 mutants killed: the capture drifting from the ledger · the caption losing its fee basis · a wall clock in the header · the SVG losing its accessible title · unescaped output breaking the XML silently · the README dropping the honesty caption · the capture built from a fixture rather than a real run.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KZZxmspQXe5qJ9FAsG13s6