The section landed in docs/TROUBLESHOOTING.md, a flat file removed in
a94e9493 when the docs were consolidated. Content there does not reach
the published guide, and the copy reintroduced install guidance that
develop had already pinned to --branch master.
Move the answer into docs/guide/resources/troubleshooting.md and drop the
duplicated Type Kit collision section, which that guide already covers.
The cache write/read breakdown is reported by `rtk cc-economics`, not by
`rtk gain`, so point readers at the command that actually shows it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Restore to develop the files where the rescoping added noise without
helping a reader: all of .claude/, the src/ module READMEs that only
described their own filters, ARCHITECTURE.md, TELEMETRY.md, quick-start,
configuration and troubleshooting.
Also drop the "Two estimators, one caveat" table from savings-explained.md.
The page already states that rtk gain estimates bytes/4 and ships no
tokenizer; enumerating the test-side estimator was detail no reader needs.
The user-facing surface keeps the rescoping: READMEs in seven languages,
the guide, hooks, and the analytics and usage pages.
The arrow diagram read as a pipeline where bash output becomes input tokens
which become cost. The real relationship is containment: bash output is
part of input tokens, and input tokens are part of cost alongside output
tokens.
Replace the arrow chain with a tree in all 12 places it appeared, including
the six translated READMEs:
Cost
├─ Input tokens
│ ├─ Bash output <- the only part RTK filters
│ ├─ Your prompt
│ ├─ System prompt
│ └─ Conversation history
└─ Output tokens <- what the model writes
This also makes the dilution self-evident: RTK shrinks one leaf, so the
effect on the root is bounded by that leaf's share.
The documented release blocker was ">=60% savings", but the code never
enforced that. 23 of the 63 threshold assertions in src/ already sit below
60% (15, 20, 30, 40 and 50% appear across aws, gh, git, glab and mvn), so
the gate was aspirational rather than real.
Set the floor to 20%, pointing at the existing "Correctness VS Token
Savings" section for the reasoning rather than restating it: a modest, safe
reduction beats an aggressive one that drops information the agent needed.
Descriptive "60-90%" ranges are left alone where they report what filters
actually achieve. Only requirement statements moved to the 20% floor.
Also reduce links to savings-explained.md down to one per file, and only
from root docs and user-facing pages. Removed from docs/contributing/ and
.claude/rules/, where the surrounding text already carries the caveat.
RTK was documented as delivering "60-90% token savings", which reads as a
cost reduction. What RTK actually reduces is bash output bytes. Those are
one contributor to input tokens, which are themselves only part of a bill
that also counts output tokens, so the reduction dilutes at every step.
- add docs/guide/resources/savings-explained.md as the canonical explainer:
the savings chain, both estimators, and what RTK does not reduce
- rescope the headline claim across README (7 languages), the guide, hook
rules, agent definitions and module READMEs
- relabel per-command tables as bash output reduction, keeping every figure
- document that reported tokens are estimates: rtk gain uses bytes/4
(src/core/tracking.rs), filter tests use split_whitespace().count().
Neither is a real tokenizer, so ratios hold but absolute counts do not
Remove figures that had no source: the $3/Mtok constant and its $36
example, the +/-10% tokenization accuracy claim, the 99.5% hook-install
figure, the invented session tables in README and INSTALL, and the 30-50%
parser range.
CHANGELOG is untouched. Shipped release notes stay as a historical record.
Nicolas Le Cam