docs: token ergonomics -- runtime routing/budgets/caches and the development-side tooling

One page, two halves with a Mermaid diagram each. A: the plane's token economy (one Model per Task with a metered usd/calls budget, attribution table, credentials only in the start request, repo-facts and content-addressed reuse, replay at $0, triage-hunt-tie-break order, prefix-cache prompt order) with every cost quoted from plane-increment-1/2.json, the injection-slice and harvest records, and an honest not-yet list (no token budget in ax, triage applied not run, k and contrast fixed outside experiments). B: the development-side measurement (tool I/O 85.5%, previously 90%) and the benchmarks/dev remedies: read_guard hook, bulk_read portal, token_report, plus the practices. Linked from the nav, index, memory-and-detection and the README docs list.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo

README.md

@@ -229,6 +229,8 @@ Documentation site with flow diagrams (`docs/`, `mkdocs.yml`): `uv sync --extra
   pair corpora and the plane increment results.
 - [docs/decision-engine.md](docs/decision-engine.md): the learned decision engine.
 - [docs/threat-model.md](docs/threat-model.md): trust boundaries, sandbox and hardening.
+- [docs/token-ergonomics.md](docs/token-ergonomics.md): model spend at runtime (budgets, reuse,
+  measured costs) and in coding sessions.
 - [docs/examples.md](docs/examples.md): end-to-end walkthroughs.
 
 ## Development