docs: scope savings claims to bash output and document the estimator

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.
2026-07-22 18:33:54 +02:00
parent 194f392539
commit a1673f7428
64 changed files with 669 additions and 321 deletions
@@ -27,7 +27,7 @@ src/main.rs (Commands enum + routing)

 **Non-negotiable constraints:**
 - Startup time <10ms (zero async, single-threaded)
- Token savings ≥60% per filter
+- ≥60% reduction in bash output per filter (measured with RTK's token estimator, not billed tokens)
 - Fallback to raw command if filter fails
 - Exit codes propagated from underlying commands

@@ -74,7 +74,7 @@ Raise alarms immediately when you see:

 **Token Savings:**
 - `count_tokens()` helper in tests
- Savings ≥60% for all filters (release blocker)
+- ≥60% bash output reduction for all filters (release blocker)
 - Output: failures only, summary stats, no verbose metadata
 - Truncation strategy: consistent across filters

@@ -97,7 +97,7 @@ docker run --rm -v $(pwd):/rtk -w /rtk rust:latest cargo test --test shell_escap
 | Filter crashes | Regex panic on malformed input | Add test with empty/malformed fixture |
 | Performance regression | Regex recompiled at runtime | Check flamegraph for `Regex::new()` calls |
 | Shell escaping error | Platform-specific quoting | Test on macOS + Linux + Windows |
-| Token savings <60% | Weak condensation logic | Review filter algorithm, compare fixtures |
+| Bash output reduction <60% | Weak condensation logic | Review filter algorithm, compare fixtures |
 | Test failure | Fixture outdated or test assertion wrong | Update fixture from real command output |

 **Example hypothesis testing**:
@@ -215,7 +215,7 @@ Command::new(cmd).args(args).spawn();
 - [ ] All tests pass (`cargo test --all`)
 - [ ] Performance benchmarks pass (`hyperfine` <10ms)
 - [ ] Cross-platform tests pass (macOS + Linux)
- [ ] Token savings verified (≥60% in tests)
+- [ ] Bash output reduction verified (≥60% in tests, measured with RTK's token estimator)
 - [ ] Code formatted (`cargo fmt --all --check`)
 - [ ] Clippy clean (`cargo clippy --all-targets`)

@@ -12,7 +12,7 @@ You are a testing expert specializing in RTK's unique testing needs: command out
 ## Core Responsibilities

 - **Snapshot testing**: Use `insta` crate for output validation
- **Token accuracy**: Verify 60-90% savings claims with real fixtures
+- **Token accuracy**: Verify 60-90% bash output reduction claims with real fixtures (RTK ships no tokenizer, so percentages are reliable ratios but absolute token counts are approximate)
 - **Cross-platform**: Test bash/zsh/PowerShell compatibility
 - **Regression prevention**: Detect performance degradation in CI
 - **Integration tests**: Real command execution (git, cargo, gh, pnpm, etc.)
@@ -84,7 +84,7 @@ ls -la src/snapshots/

 ### Token Count Validation

-All filters **MUST** verify token savings claims (60-90%) in tests:
+All filters **MUST** verify their bash output reduction claims (60-90%) in tests:

 ```rust
 #[cfg(test)]
@@ -100,9 +100,9 @@ mod tests {
    #[test]
    fn test_token_savings_claim() {
        let fixtures = [
-            ("git_log", 0.80),      // 80% savings expected
-            ("cargo_test", 0.90),   // 90% savings expected
-            ("gh_pr_view", 0.87),   // 87% savings expected
+            ("git_log", 0.80),      // 80% less bash output expected
+            ("cargo_test", 0.90),   // 90% less bash output expected
+            ("gh_pr_view", 0.87),   // 87% less bash output expected
        ];

        for (name, expected_savings) in fixtures {
@@ -124,7 +124,7 @@ mod tests {
 }
 ```

-**Why critical**: RTK promises 60-90% token savings. Tests must verify these claims with real fixtures. If savings drop below 60%, it's a **release blocker**.
+**Why critical**: RTK promises 60-90% less bash output. Tests must verify these claims with real fixtures. If the reduction drops below 60% of the output bytes, it's a **release blocker**.

 **Creating fixtures**:

@@ -242,7 +242,7 @@ cargo test --ignored test_real_git_log

 **Coverage goals**:
 - **100% filter coverage**: Every filter has snapshot test + token accuracy test
- **95% token savings verification**: Fixtures with known savings (60-90%)
+- **95% savings verification**: Fixtures with known bash output reduction (60-90%)
 - **Cross-platform tests**: macOS + Linux (Windows in CI only)

 **Coverage verification**:
@@ -300,8 +300,8 @@ docker run --rm -v $(pwd):/rtk -w /rtk rust:latest cargo test
 - Memory usage must be <5MB
 - Use `hyperfine` and `time -l` to verify

-❌ **DON'T** accept <60% token savings → Fails promise to users
- All filters must achieve 60-90% savings
+❌ **DON'T** accept <60% bash output reduction → Fails promise to users
+- All filters must cut 60-90% of the output bytes
 - Test with real fixtures, not synthetic data
 - If savings drop, investigate and fix before merge

@@ -89,7 +89,7 @@ pub fn filter_git_log(input: &str) -> String {

 ### Token Count Validation (Testing Critical)

-All filters **MUST** verify token savings claims (60-90%) in tests:
+All filters **MUST** verify their bash output reduction claims (60-90%) in tests. The gate measures shell output with RTK's token estimator, not billed tokens:

 ```rust
 #[cfg(test)]
@@ -113,7 +113,7 @@ mod tests {

        let savings = 100.0 - (output_tokens as f64 / input_tokens as f64 * 100.0);

-        // RTK promise: 60-90% savings
+        // RTK promise: 60-90% less bash output
        assert!(
            savings >= 60.0,
            "Git log filter: expected ≥60% savings, got {:.1}%",
@@ -126,7 +126,7 @@ mod tests {
 }
 ```

-**Why**: Token savings claims (60-90%) must be **verifiable**. Tests with real fixtures prevent regressions. If savings drop below 60%, it's a release blocker.
+**Why**: The 60-90% bash output reduction claims must be **verifiable**. Tests with real fixtures prevent regressions. If the reduction drops below 60% of the output bytes, it's a release blocker.

 ### Cross-Platform Shell Escaping

@@ -395,7 +395,7 @@ docker run --rm -v $(pwd):/rtk -w /rtk rust:latest cargo test  # Linux via Docke

 ✅ **DO** provide fallback to raw command on filter failure
 ✅ **DO** compile regex once with `lazy_static!`
-✅ **DO** verify token savings claims in tests (≥60%)
+✅ **DO** verify bash output reduction claims in tests (≥60%)
 ✅ **DO** test on macOS + Linux + Windows (via CI or manual)
 ✅ **DO** run `cargo fmt && cargo clippy --all-targets && cargo test` before commit
 ✅ **DO** benchmark startup time with `hyperfine` (<10ms target)
@@ -517,7 +517,7 @@ rtk newcmd args
 |--------|--------|--------------|
 | Startup time | <10ms | `hyperfine 'rtk git status'` |
 | Memory overhead | <5MB | `/usr/bin/time -l rtk git status` |
-| Token savings | 60-90% | Tests with `count_tokens()` |
+| Bash output reduction | 60-90% | Tests with `count_tokens()` |
 | Binary size | <5MB stripped | `ls -lh target/release/rtk` |

 **Performance regressions are release blockers** - always benchmark before/after changes.
@@ -122,7 +122,7 @@ max_lines = 50
 ```

 Use TOML DSL when: simple grep/strip transformations.
-Use Rust module when: complex parsing, structured output (JSON/NDJSON), token savings >80%.
+Use Rust module when: complex parsing, structured output (JSON/NDJSON), bash output reduction >80%.

 ### Pattern 4: Shared Utilities

@@ -181,5 +181,5 @@ Before adding code to a module, check `utils.rs`:
 **Will not:**
 - Implement the full filter logic (→ rust-rtk agent)
 - Write the actual regex patterns (→ implementation detail)
- Make decisions about token savings targets (→ fixed at ≥60%)
+- Make decisions about savings targets (→ fixed at ≥60% reduction in bash output)
 - Override the <10ms startup constraint (→ non-negotiable)
@@ -28,7 +28,7 @@ Write for developers using RTK, not for yourself. Prioritize clarity with workin
 ## Key Actions RTK

 1. **Document CLI Commands**: Clear syntax, flags, examples with real output
-2. **Evidence Performance Claims**: Benchmark data supporting 60-90% token savings
+2. **Evidence Performance Claims**: Benchmark data supporting the 60-90% bash output reduction. Never restate it as a cost or billed-token saving: RTK filters shell output bytes, which are one contributor to input tokens, and input tokens are only part of a bill that also counts output tokens.
 3. **Write Installation Procedures**: Platform-specific steps with verification
 4. **Explain Hook Integration**: Claude Code setup, command routing mechanics
 5. **Guide Filter Development**: Contribution workflow, testing patterns, quality standards
@@ -55,7 +55,7 @@ rtk git log -10
 rtk git log --oneline --graph -20
 ```

-**Token Savings**: 80% (verified with fixtures)
+**Bash Output Reduction**: 80% (verified with fixtures)
 **Performance**: <10ms startup

 **Expected Output**:
@@ -68,16 +68,16 @@ commit def5678 Fix bug Y

 ### Performance Claims Documentation
 ```markdown
-## Token Savings Evidence
+## Bash Output Reduction Evidence

 **Methodology**:
 - Fixtures: Real command output from production environments
- Measurement: Whitespace-based tokenization (`count_tokens()`)
- Verification: Tests enforce ≥60% savings threshold
+- Measurement: Whitespace-based tokenization (`count_tokens()`); `rtk gain` uses a `bytes / 4` estimator, so percentages are reliable ratios and absolute token counts are approximate
+- Verification: Tests enforce a ≥60% reduction in bash output bytes

 **Results by Filter**:

-| Filter | Input Tokens | Output Tokens | Savings | Fixture |
+| Filter | Input Tokens (est.) | Output Tokens (est.) | Output Reduction | Fixture |
 |--------|--------------|---------------|---------|---------|
 | `git log` | 2,450 | 489 | 80.0% | tests/fixtures/git_log_raw.txt |
 | `cargo test` | 8,120 | 812 | 90.0% | tests/fixtures/cargo_test_raw.txt |
@@ -97,7 +97,7 @@ Range (min … max):     5.8 ms …   7.1 ms    100 runs
 # Run token accuracy tests
 cargo test test_token_savings

-# All tests should pass, enforcing ≥60% savings
+# All tests should pass, enforcing a ≥60% bash output reduction
 ```
 ```

@@ -189,7 +189,7 @@ RTK integrates with Claude Code via bash hooks for transparent command rewriting
 2. Hook (`rtk-rewrite.sh`) intercepts command
 3. Rewrites to: `rtk git status`
 4. RTK applies filter, returns condensed output
-5. Claude sees token-optimized result (80% savings)
+5. Claude sees token-optimized result (80% less bash output)

 ## Hook Files

@@ -283,7 +283,7 @@ newcmd --args > tests/fixtures/newcmd_raw.txt
 cargo test
 ```

-### 4. Document Token Savings
+### 4. Document Bash Output Reduction

 Update README.md:
 ```markdown
@@ -298,7 +298,7 @@ cargo fmt --all && cargo clippy --all-targets && cargo test --all

 ## Filter Quality Standards

- **Token savings**: ≥60% verified in tests
+- **Bash output reduction**: ≥60% verified in tests
 - **Startup time**: <10ms with `hyperfine`
 - **Lazy regex**: All patterns in `lazy_static!`
 - **Error handling**: Fallback to raw command on failure
@@ -342,7 +342,7 @@ A tests/new_test.rs
 **Performance claims**:
 ```markdown
 # ✅ Good: Evidence with fixture
-Token savings: 80% (2,450 → 489 tokens)
+Bash output reduction: 80% (2,450 → 489 estimated tokens)
 Fixture: tests/fixtures/git_log_raw.txt
 Verification: cargo test test_git_log_savings
 ```
@@ -13,7 +13,7 @@ Vérifie l'état de l'environnement RTK et suggère des corrections.
  - `rtk: command not found` → RTK non installé ou pas dans PATH
  - Hook errors in Claude Code → Hooks mal configurés ou non exécutables
  - `Unknown command` dans RTK → Version incompatible ou commande non supportée
-  - Token savings reports missing → `rtk gain` not working
+  - Savings dashboard missing → `rtk gain` not working
  - Command routing errors → Hook integration broken

 - **Manuellement** après installation, mise à jour RTK, ou si comportement suspect
@@ -94,7 +94,7 @@ fi
 # Run rtk gain to verify analytics work
 if command -v rtk >/dev/null 2>&1; then
    echo ""
-    echo "📊 Token Savings (last 5 commands):"
+    echo "📊 Bash output reduction (last 5 commands):"
    rtk gain --history 2>&1 | head -8 || echo "⚠️ rtk gain failed"
 else
    echo "⚠️ Cannot test rtk gain (binary not installed)"
@@ -157,7 +157,7 @@ echo "Test coverage: $TESTED / $MODULES modules"
 # Fixtures réelles présentes
 Glob tests/fixtures/*.txt | wc -l

-# Tests de token savings (count_tokens assertions)
+# Tests de reduction de sortie bash (count_tokens assertions)
 Grep "count_tokens\|savings" src/ --glob "*.rs" --output_mode count

 # Smoke tests OK
@@ -84,7 +84,7 @@ git diff "$BASE_BRANCH"...HEAD --stat
 **Tests**:
 - `#[cfg(test)] mod tests` embarqué dans chaque module
 - Fixtures réelles dans `tests/fixtures/<cmd>_raw.txt`
- `count_tokens()` pour vérifier savings ≥60%
+- `count_tokens()` pour vérifier ≥60% de réduction de la sortie bash
 - `assert_snapshot!` (insta) pour output format

 **Module**:
@@ -93,7 +93,7 @@ git diff "$BASE_BRANCH"...HEAD --stat
 - `strip_ansi()` depuis `utils.rs` — pas re-implémenté

 **Filtres**:
- Token savings ≥60% obligatoire (release blocker)
+- Réduction ≥60% de la sortie bash obligatoire, mesurée avec l'estimateur de tokens de RTK et non des tokens facturés (release blocker)
 - Fallback: si filter échoue → raw command exécutée
 - Pas d'output ASCII art, pas de verbose metadata inutile

@@ -105,7 +105,7 @@ git diff "$BASE_BRANCH"...HEAD --stat
 - `Regex::new()` dans une fonction (pas de lazy_static)
 - `?` sans `.context()` — erreur sans description
 - Dépendance async ajoutée (tokio, async-std, futures)
- Token savings <60% pour un nouveau filtre
+- Réduction de la sortie bash <60% pour un nouveau filtre
 - Pas de fallback vers commande brute sur échec de filtre
 - `panic!()` en production (hors tests)
 - Exit code non propagé sur commande sous-jacente
@@ -113,7 +113,7 @@ git diff "$BASE_BRANCH"...HEAD --stat
 - **Tests manquants pour NOUVEAU code** :
  - Nouveau `*_cmd.rs` sans `#[cfg(test)] mod tests`
  - Nouveau filtre sans fixture réelle dans `tests/fixtures/`
-  - Nouveau filtre sans test de token savings (`count_tokens()`)
+  - Nouveau filtre sans test de réduction de sortie (`count_tokens()`)

 ### 🟡 SHOULD FIX (important)

@@ -55,7 +55,7 @@ else
    echo ""
    echo "Expected behavior:"
    echo "  - Command executed without RTK filtering"
-    echo "  - Full command output (no token savings)"
+    echo "  - Full command output (no filtering)"
    echo "  - Original command behavior unchanged"
 fi
 ```
@@ -111,23 +111,23 @@ if [[ " ${RTK_COMMANDS[@]} " =~ " ${COMMAND} " ]]; then
    case "$COMMAND" in
        git)
            echo "Filter: git operations (status, log, diff, etc.)"
-            echo "Token savings: 60-80% depending on subcommand"
+            echo "Bash output reduction: 60-80% depending on subcommand"
            ;;
        cargo)
            echo "Filter: cargo build/test/clippy output"
-            echo "Token savings: 80-90% (failures only for tests)"
+            echo "Bash output reduction: 80-90% (failures only for tests)"
            ;;
        gh)
            echo "Filter: GitHub CLI (pr, issue, run)"
-            echo "Token savings: 26-87% depending on subcommand"
+            echo "Bash output reduction: 79-87% depending on subcommand"
            ;;
        pnpm)
            echo "Filter: pnpm package manager"
-            echo "Token savings: 70-90% (dependency trees)"
+            echo "Bash output reduction: 70-90% (dependency trees)"
            ;;
        *)
            echo "Filter: Available for $COMMAND"
-            echo "Token savings: 60-90% (typical)"
+            echo "Bash output reduction: 60-90% (typical)"
            ;;
    esac
 else
@@ -176,22 +176,22 @@ if rtk --help | grep -E "^  $COMMAND" >/dev/null 2>&1; then
    echo "  Filter: Applied"
    echo ""

-    # Estimate token savings (based on historical data)
+    # Estimate bash output reduction (based on historical data)
    case "$COMMAND" in
        git)
-            echo "Expected Token Savings: 60-80%"
+            echo "Expected bash output reduction: 60-80%"
            echo "Startup Time: <10ms"
            ;;
        cargo)
-            echo "Expected Token Savings: 80-90%"
+            echo "Expected bash output reduction: 80-90%"
            echo "Startup Time: <10ms"
            ;;
        gh)
-            echo "Expected Token Savings: 26-87%"
+            echo "Expected bash output reduction: 79-87%"
            echo "Startup Time: <10ms"
            ;;
        *)
-            echo "Expected Token Savings: 60-90%"
+            echo "Expected bash output reduction: 60-90%"
            echo "Startup Time: <10ms"
            ;;
    esac
@@ -234,7 +234,7 @@ Routing:
  Route:  rtk git status
  Filter: Applied

-Expected Token Savings: 60-80%
+Expected bash output reduction: 60-80%
 Startup Time: <10ms

 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -329,7 +329,7 @@ Identifier commandes sans filtre qui pourraient bénéficier :
 # ⚠️  No filter

 # Consider contributing pytest filter
-# Expected savings: 90% (failures only)
+# Expected bash output reduction: 90% (failures only)
 # Complexity: Medium (JSON output parsing)
 ```

@@ -347,7 +347,7 @@ Dans Claude Code, cette command permet de :
 User: "Is git status supported by RTK?"
 Assistant: "Let me check with /test-routing git status"
 [Runs command]
-Assistant: "Yes! RTK has a filter for git status with 60-80% token savings."
+Assistant: "Yes! RTK has a filter for git status cutting 60-80% of its bash output."
 ```

 ## Limitations
@@ -74,7 +74,10 @@ cargo test test_mvn_test_example

 **Priority**: 🔴 **Triggers**: All filter implementations, token savings claims

-All filters **MUST** verify 60-90% token savings claims with real fixtures.
+All filters **MUST** verify their 60-90% claims with real fixtures. What is measured is the
+**reduction in bash output**. RTK ships no tokenizer: tests count whitespace-separated tokens,
+`rtk gain` estimates `bytes / 4`. Both are reliable as ratios and approximate as absolute token
+counts. See [How RTK Savings Work](../../docs/guide/resources/savings-explained.md).

 ### Token Count Test

@@ -121,8 +124,9 @@ pnpm list > tests/fixtures/pnpm_list_raw.txt

 ### Savings Target

-There is a single enforced floor, not a per-filter table: **≥60% savings is the release
-blocker** (see CLAUDE.md's "Pre-commit Gate" / performance targets). Individual filters often
+There is a single enforced floor, not a per-filter table: **≥60% reduction in bash output is
+the release blocker** (see CLAUDE.md's "Pre-commit Gate" / performance targets).
+Individual filters often
 exceed this by a wide margin, but don't assert specific per-command percentages (e.g. "87% for
 `gh pr view`") unless you've verified the actual number against that filter's own fixtures —
 asserted thresholds vary per filter and doc tables listing invented numbers rot immediately.
@@ -344,7 +348,7 @@ When adding/modifying a filter:
 ### Implementation Phase
 - [ ] Write a unit test in the filter's own `#[cfg(test)] mod tests` block (inline string, or
      `include_str!` fixture for larger/real output)
- [ ] Add a token accuracy test (verify ≥60% savings) using a locally-defined `count_tokens`
+- [ ] Add a token accuracy test (verify ≥60% bash output reduction) using a locally-defined `count_tokens`
 - [ ] Test cross-platform shell escaping (if applicable)

 ### Quality Checks
@@ -354,7 +358,7 @@ When adding/modifying a filter:

 ### Before Merge
 - [ ] All tests passing (`cargo test --all`)
- [ ] Token savings ≥60% verified
+- [ ] ≥60% bash output reduction verified
 - [ ] Cross-platform tests passed (Linux + macOS)
 - [ ] Performance benchmarks passed (<10ms startup)

@@ -532,7 +536,7 @@ hyperfine 'target/release/rtk cmd' --warmup 3 > /tmp/after.txt
 diff /tmp/before.txt /tmp/after.txt
 ```

-❌ **DON'T** accept <60% token savings
+❌ **DON'T** accept <60% bash output reduction
 ```rust
 // ❌ WRONG - no savings verification
 #[test]
@@ -1,10 +1,10 @@
 ---
-description: CLI performance optimization - startup time, memory usage, token savings benchmarking
+description: CLI performance optimization - startup time, memory usage, bash output reduction benchmarking
 ---

 # Performance Optimization Skill

-Systematic performance analysis and optimization for RTK CLI tool, focusing on **startup time (<10ms)**, **memory usage (<5MB)**, and **token savings (60-90%)**.
+Systematic performance analysis and optimization for RTK CLI tool, focusing on **startup time (<10ms)**, **memory usage (<5MB)**, and **bash output reduction (60-90%)**.

 ## When to Use

@@ -18,7 +18,7 @@ Systematic performance analysis and optimization for RTK CLI tool, focusing on *
 |--------|--------|---------------------|-------------------|
 | **Startup time** | <10ms | `hyperfine 'rtk <cmd>'` | >15ms = blocker |
 | **Memory usage** | <5MB resident | `/usr/bin/time -l rtk <cmd>` (macOS) | >7MB = blocker |
-| **Token savings** | 60-90% | Tests with `count_tokens()` | <60% = blocker |
+| **Bash output reduction** | 60-90% | Tests with `count_tokens()` (bytes/4 estimator) | <60% = blocker |
 | **Binary size** | <5MB stripped | `ls -lh target/release/rtk` | >8MB = investigate |

 ## Performance Analysis Workflow
@@ -112,7 +112,7 @@ cargo install dhat
 # static ALLOC: dhat::Alloc = dhat::Alloc;
 ```

-**Token savings regression** (<60% savings):
+**Bash output reduction regression** (<60%):
 ```bash
 # Run token accuracy tests
 cargo test test_token_savings
@@ -329,9 +329,9 @@ Before committing filter changes:
 - [ ] Verify <5MB resident set size
 - [ ] Compare against baseline (regression <1MB)

-### Token Savings
+### Bash Output Reduction
 - [ ] Run `cargo test test_token_savings`
- [ ] Verify all filters achieve ≥60% savings
+- [ ] Verify all filters achieve ≥60% bash output reduction
 - [ ] Check real fixtures used (not synthetic)

 ### Binary Size
@@ -228,7 +228,7 @@ prompt: |
  - anyhow::Result + .context() (no unwrap())
  - Fallback to raw command on filter failure
  - Exit code propagation
-  - Token savings ≥60% in tests with real fixtures
+  - Bash output reduction ≥60% in tests with real fixtures
  - No async/tokio dependencies

  Return structured review:
@@ -53,7 +53,7 @@ Use this template to generate GitHub PR review comments. Fill in each section ba

 **Issue severity** :
 - 🔴 Critical : security vulnerability, data loss risk, broken functionality, test missing for new feature
- 🟡 Important : error handling gap, performance regression, scope creep, missing token savings assertion
+- 🟡 Important : error handling gap, performance regression, scope creep, missing bash output reduction assertion
 - 🟢 Suggestion : naming, DRY opportunity, documentation, style

 **RTK-specific checks to mention if relevant** :
@@ -61,7 +61,7 @@ Use this template to generate GitHub PR review comments. Fill in each section ba
 - `anyhow::Result` + `.context("msg")` (no bare `?`, no `.unwrap()`)
 - Fallback to raw command on filter failure
 - Exit code propagation (`std::process::exit(code)`)
- Token savings assertion ≥60% in tests
+- Bash output reduction assertion ≥60% in tests
 - Real fixtures (not synthetic test data)
 - No async/tokio dependencies (startup time)

@@ -1,6 +1,6 @@
 ---
 name: tdd-rust
-description: TDD workflow for RTK filter development. Red-Green-Refactor with Rust idioms. Real fixtures, token savings assertions, snapshot tests with insta. Auto-triggers on new filter implementation.
+description: TDD workflow for RTK filter development. Red-Green-Refactor with Rust idioms. Real fixtures, bash output reduction assertions, snapshot tests with insta. Auto-triggers on new filter implementation.
 triggers:
  - "new filter"
  - "implement filter"
@@ -14,7 +14,7 @@ allowed-tools:
  - Edit
  - Bash
 effort: medium
-tags: [tdd, testing, rust, filters, snapshots, token-savings, rtk]
+tags: [tdd, testing, rust, filters, snapshots, bash-output-reduction, rtk]
 ---

 # RTK TDD Workflow
@@ -68,7 +68,7 @@ mod tests {
        assert_snapshot!(output);
    }

-    // Test 2: Token savings ≥60%
+    // Test 2: Bash output reduction ≥60%
    #[test]
    fn test_token_savings() {
        let input = include_str!("../tests/fixtures/mycmd_raw.txt");
@@ -80,7 +80,7 @@ mod tests {

        assert!(
            savings >= 60.0,
-            "Expected ≥60% token savings, got {:.1}% ({} → {} tokens)",
+            "Expected ≥60% bash output reduction, got {:.1}% ({} → {} est. tokens)",
            savings, input_tokens, output_tokens
        );
    }
@@ -259,7 +259,7 @@ Checklist before moving on:
 - [ ] `tests/fixtures/<cmd>_raw.txt` — real command output
 - [ ] `filter_<cmd>()` function returns `Result<String>`
 - [ ] Snapshot test passes and accepted via `cargo insta review`
- [ ] Token savings test: ≥60% verified
+- [ ] Bash output reduction test: ≥60% verified
 - [ ] Empty input test: no panic
 - [ ] Malformed input test: no panic
 - [ ] `run()` function with fallback pattern
@@ -272,11 +272,11 @@ Checklist before moving on:
 // ❌ Synthetic fixture data
 let input = "fake error: something went wrong";  // Not real cargo output

-// ❌ Missing savings test
+// ❌ Missing bash output reduction test
 #[test]
 fn test_filter() {
    let output = filter_mycmd(input);
-    assert!(!output.is_empty());  // No savings verification
+    assert!(!output.is_empty());  // No bash output reduction verification
 }

 // ❌ unwrap() in production code
@@ -1,6 +1,6 @@
 # Copilot Instructions for rtk

-**rtk (Rust Token Killer)** is a CLI proxy that filters and compresses command outputs before they reach an LLM context, saving 60-90% of tokens. It wraps common tools (`git`, `cargo`, `grep`, `pnpm`, `go`, etc.) and outputs condensed summaries instead of raw output.
+**rtk (Rust Token Killer)** is a CLI proxy that filters and compresses command outputs before they reach an LLM context, cutting 60-90% of bash output. It wraps common tools (`git`, `cargo`, `grep`, `pnpm`, `go`, etc.) and outputs condensed summaries instead of raw output. Percentages measure bash output, not billed tokens; RTK ships no tokenizer (`src/core/tracking.rs` estimates `bytes / 4`).

 ## Using rtk in this session

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 ## Project Overview

-**rtk (Rust Token Killer)** is a high-performance CLI proxy that minimizes LLM token consumption by filtering and compressing command outputs. It achieves 60-90% token savings on common development operations through smart filtering, grouping, truncation, and deduplication.
+**rtk (Rust Token Killer)** is a high-performance CLI proxy that minimizes LLM token consumption by filtering and compressing command outputs. It reduces bash output by 60-90% on common development operations through smart filtering, grouping, truncation, and deduplication. All percentages in this repo measure bash output, not your bill. RTK ships no tokenizer (`src/core/tracking.rs` estimates tokens as `bytes / 4`), so the ratios are reliable but the absolute token counts are approximate.

 This is a fork with critical fixes for git argument parsing and modern JavaScript stack support (pnpm, vitest, Next.js, TypeScript, Playwright, Prisma).

@@ -95,7 +95,7 @@ rtk proxy npm install express      # Raw npm output (no filtering)
 rtk proxy curl https://api.example.com/data  # Any command works
 ```

-All proxy commands appear in `rtk gain --history` with 0% savings (input = output).
+All proxy commands appear in `rtk gain --history` with 0% bash output reduction (input = output).

 ## Coding Rules

@@ -108,7 +108,7 @@ Rust patterns, error handling, and anti-patterns are defined in `.claude/rules/r
 - **No async**: single-threaded by design (startup <10ms)
 - **Exit code propagation**: `std::process::exit(code)` on child failure

-Testing strategy and performance targets are defined in `.claude/rules/cli-testing.md` (auto-loaded). Key targets: <10ms startup, <5MB memory, 60-90% token savings.
+Testing strategy and performance targets are defined in `.claude/rules/cli-testing.md` (auto-loaded). Key targets: <10ms startup, <5MB memory, 60-90% reduction in bash output bytes.

 For contribution workflow and design philosophy, see [CONTRIBUTING.md](CONTRIBUTING.md). For the step-by-step filter implementation checklist, see [src/cmds/README.md](src/cmds/README.md#adding-a-new-command-filter).

@@ -13,7 +13,9 @@

 ## What is rtk?

-**rtk (Rust Token Killer)** is a coding agent proxy that cuts noise from command outputs. It filters and compresses CLI output before it reaches your LLM context, saving 60-90% of tokens on common operations. The vision is to make AI-assisted development faster and cheaper by eliminating unnecessary token consumption.
+**rtk (Rust Token Killer)** is a coding agent proxy that cuts noise from command outputs. It filters and compresses CLI output before it reaches your LLM context, reducing bash output by 60-90% on common operations. The vision is to make AI-assisted development faster and cheaper by eliminating unnecessary token consumption.
+
+Every percentage in this repo measures **bash output**, not your bill: those bytes are one contributor to input tokens, and input tokens are only part of a cost that also counts output tokens. See [How RTK Savings Work](docs/guide/resources/savings-explained.md) before quoting any figure.

 ---

@@ -38,7 +40,7 @@ When a user or LLM explicitly requests detailed output via flags (e.g., `git log

 Filters should be flag-aware: default output (no flags) gets aggressively compressed, but verbose/detailed flags should pass through more content. When in doubt, preserve correctness.

-> Example: `rtk cargo test` shows failures only (90% savings). But `rtk cargo test -- --nocapture` preserves all output because the user explicitly asked for it.
+> Example: `rtk cargo test` shows failures only (90% less bash output). But `rtk cargo test -- --nocapture` preserves all output because the user explicitly asked for it.

 ### Transparency

@@ -71,7 +73,7 @@ If you want to submit a new core feature, this is an important point to watch.

 ### In Scope

-Commands that produce **text output** (typically 100+ tokens) and can be compressed **60%+** without losing essential information for the LLM.
+Commands that produce **text output** (typically 100+ tokens) whose bytes can be compressed **60%+** without losing essential information for the LLM.

 - Test runners (vitest, pytest, cargo test, go test)
 - Linters and type checkers (eslint, ruff, tsc, mypy)
@@ -96,7 +98,7 @@ When implementing a new filter/cmds, be aware of the [Design Philosophy](#design
 | Use **TOML filter** when | Use **Rust module** when |
 |--------------------------|--------------------------|
 | Output is plain text with predictable line structure | Output is structured (JSON, NDJSON) |
-| Regex line filtering achieves 60%+ savings | Needs state machine parsing (e.g., pytest phases) |
+| Regex line filtering cuts 60%+ of the output bytes | Needs state machine parsing (e.g., pytest phases) |
 | No need to inject CLI flags | Needs to inject flags like `--format json` |
 | No cross-command routing | Routes to other commands (lint → ruff/mypy) |
 | Examples: brew, df, shellcheck, rsync, ping | Examples: vitest, pytest, golangci-lint, gh |
@@ -263,7 +265,7 @@ cargo fmt --all --check && cargo clippy --all-targets && cargo test

 - [ ] Unit tests added/updated for changed code
 - [ ] Snapshot tests for filters
- [ ] Token savings >=60% verified
+- [ ] >=60% reduction in bash output verified (measured with RTK's token estimator, not a real tokenizer)
 - [ ] Any truncated list has a recovery hint (`force_tee_tail_hint` or `force_tee_hint`) and uses a `CAP_*` from `src/core/truncate.rs`
 - [ ] Edge cases covered
 - [ ] `cargo fmt --all --check && cargo clippy --all-targets && cargo test` passes
@@ -6,7 +6,7 @@

 1. ✅ **Rust Token Killer** (this project) - LLM token optimizer
   - Repos: `rtk-ai/rtk`
-   - Has `rtk gain` command for token savings stats
+   - Has `rtk gain` command showing the savings dashboard

 2. ❌ **Rust Type Kit** (reachingforthejack/rtk) - DIFFERENT PROJECT
   - Rust codebase query tool and type generator
@@ -21,7 +21,7 @@
 rtk --version

 # CRITICAL: Verify it's the Token Killer (not Type Kit)
-rtk gain    # Should show token savings stats, NOT "command not found"
+rtk gain    # Should show the savings dashboard, NOT "command not found"

 # Check installation path
 which rtk
@@ -49,7 +49,7 @@ curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh

 After installation, **verify you have the correct rtk**:
 ```bash
-rtk gain  # Must show token savings stats (not "command not found")
+rtk gain  # Must show the savings dashboard (not "command not found")
 ```

 ### Alternative: Manual Installation
@@ -62,7 +62,7 @@ cargo install --git https://github.com/rtk-ai/rtk
 cargo install rtk

 # ALWAYS VERIFY after installation
-rtk gain  # MUST show token savings, not "command not found"
+rtk gain  # MUST show the savings dashboard, not "command not found"
 ```

 ⚠️ **WARNING**: `cargo install rtk` from crates.io might install the wrong package. Always verify with `rtk gain`.
@@ -107,7 +107,7 @@ rtk init -g --no-patch      # Print manual instructions instead
 rtk init --show  # Check hook is installed and executable
 ```

-**Token savings**: ~99.5% reduction (2000 tokens → 10 tokens in context)
+**Context cost**: the hook adds a 10-line `RTK.md` to your context instead of a full command reference, and rewrites commands transparently at no per-command context cost.

 **What is settings.json?**
 Claude Code's hook registry. RTK adds a PreToolUse hook that rewrites commands transparently. Without this, Claude won't invoke the hook automatically.
@@ -146,7 +146,7 @@ cd /path/to/your/project
 rtk init  # Creates ./CLAUDE.md with full RTK instructions (137 lines)
 ```

-**Token savings**: Instructions loaded only for this project
+**Context cost**: instructions loaded only for this project

 ### Upgrading from Previous Version

@@ -180,7 +180,7 @@ rtk init --show
 ```bash
 # 1. Install RTK
 cargo install --git https://github.com/rtk-ai/rtk
-rtk gain  # Verify (must show token stats)
+rtk gain  # Verify (must show the savings dashboard)

 # 2. Setup with prompts
 rtk init -g
@@ -294,9 +294,11 @@ rtk git commit -m "msg"  # → "ok ✓ abc1234"
 rtk git push          # → "ok ✓ main"
 ```

+> Percentages below are **reductions in bash output**, not reductions in your bill.
+
 ### Pnpm (fork only)
 ```bash
-rtk pnpm list     # Dependency tree (-70% tokens)
+rtk pnpm list     # Dependency tree (-70%)
 rtk pnpm outdated # Available updates (-80-90%)
 rtk pnpm install  # Silent installation
 ```
@@ -316,25 +318,26 @@ rtk test <cmd>      # Generic test wrapper - failures only (-90%)

 ### Statistics
 ```bash
-rtk gain              # Token savings
+rtk gain              # Savings dashboard
 rtk gain --graph      # With ASCII graph
 rtk gain --history    # With command history
 ```

-## Validated Token Savings
+## What RTK Filters

-### Production T3 Stack Project
-| Operation | Standard | RTK | Reduction |
-|-----------|----------|-----|-----------|
-| `vitest` | 102,199 chars | 377 chars | **-99.6%** |
-| `git status` | 529 chars | 217 chars | **-59%** |
-| `pnpm list` | ~8,000 tokens | ~2,400 | **-70%** |
-| `pnpm outdated` | ~12,000 tokens | ~1,200-2,400 | **-80-90%** |
+RTK compresses the output of a shell command before your agent reads it. What that looks like in practice:

-### Typical Claude Code Session (30 min)
- **Without RTK**: ~150,000 tokens
- **With RTK**: ~45,000 tokens
- **Savings**: **70% reduction**
+| Operation | What RTK does to the output |
+|-----------|-----------------------------|
+| `vitest` / `jest` | Failures only; passing suites collapse to a count |
+| `git status` | Compact stat format, grouped by state |
+| `pnpm list` | Compact dependency tree |
+| `pnpm outdated` | Package, current and target version only |
+| `cargo test` | Failures only, with the assertion and location |
+
+The percentages shown next to commands above are **reductions in bash output bytes**. That is the part RTK controls — it is not the same as reducing your bill by the same amount, because bash output is only one contributor to input tokens, and input tokens are only part of a bill that also counts output tokens.
+
+See [How RTK Savings Work](docs/guide/resources/savings-explained.md) for the full explanation, including why the token counts RTK reports are estimates.

 ## Troubleshooting

@@ -3,7 +3,7 @@
 </p>

 <p align="center">
-  <strong>High-performance CLI proxy that reduces LLM token consumption by 60-90%</strong>
+  <strong>High-performance CLI proxy that cuts up to 90% of the bash output your agent reads</strong>
 </p>

 <p align="center">
@@ -36,25 +36,40 @@

 rtk filters and compresses command outputs before they reach your LLM context. Single Rust binary, 100+ supported commands, <10ms overhead.

-## Token Savings (30-min Claude Code Session)
+## What RTK Does

-| Operation | Frequency | Standard | rtk | Savings |
-|-----------|-----------|----------|-----|---------|
-| `ls` / `tree` | 10x | 2,000 | 400 | -80% |
-| `cat` / `read` | 20x | 40,000 | 12,000 | -70% |
-| `grep` / `rg` | 8x | 16,000 | 3,200 | -80% |
-| `git status` | 10x | 3,000 | 600 | -80% |
-| `git diff` | 5x | 10,000 | 2,500 | -75% |
-| `git log` | 5x | 2,500 | 500 | -80% |
-| `git add/commit/push` | 8x | 1,600 | 120 | -92% |
-| `cargo test` / `npm test` | 5x | 25,000 | 2,500 | -90% |
-| `ruff check` | 3x | 3,000 | 600 | -80% |
-| `pytest` | 4x | 8,000 | 800 | -90% |
-| `go test` | 3x | 6,000 | 600 | -90% |
-| `docker ps` | 3x | 900 | 180 | -80% |
-| **Total** | | **~118,000** | **~23,900** | **-80%** |
+RTK intercepts shell commands and compresses their output before your agent reads it.

-> Estimates based on medium-sized TypeScript/Rust projects. Actual savings vary by project size.
+| Operation | What RTK does to the output |
+|-----------|-----------------------------|
+| `ls` / `tree` | Tree format with file counts instead of one line per entry |
+| `cat` / `read` | Smart file reading: signatures and structure over full bodies |
+| `grep` / `rg` | Truncates long lines, groups matches by file |
+| `git status` | Compact stat format, grouped by state |
+| `git diff` | Reduced context, headers stripped |
+| `git log` | Hash, author and subject only |
+| `git add/commit/push` | Confirmation line instead of full progress output |
+| `cargo test` / `npm test` | Failures only, passing tests collapsed to a count |
+| `ruff check` | Grouped by rule and file |
+| `pytest` | Failures only, traceback trimmed |
+| `go test` | NDJSON parsed, failures only |
+| `docker ps` | Essential fields only |
+
+## How Savings Work
+
+RTK cuts **up to 90% of the bash output** your agent reads. That is what RTK measures, and it is not the same as cutting your bill by 90%.
+
+```
+Bash output bytes  ->  Input tokens  ->  Cost
+ what RTK filters      one input source     input + output tokens
+                       among several
+```
+
+Bash output is **one contributor to input tokens**, alongside your prompt, the system prompt and conversation history. Input tokens are in turn **only part of the bill**, which also counts output tokens. The reduction dilutes at every step.
+
+The token counts RTK reports are estimated as `bytes / 4` — RTK ships no tokenizer, so the **percentages are reliable but the absolute token numbers are approximate**.
+
+> Full explanation: [How RTK Savings Work](docs/guide/resources/savings-explained.md)

 ## Installation

@@ -94,7 +109,7 @@ Download from [releases](https://github.com/rtk-ai/rtk/releases):

 ```bash
 rtk --version   # Should show "rtk 0.28.2"
-rtk gain        # Should show token savings stats
+rtk gain        # Should show the savings dashboard
 ```

 > **Name collision warning**: Another project named "rtk" (Rust Type Kit) exists on crates.io. If `rtk gain` fails, you have the wrong package. Use `cargo install --git` above instead.
@@ -131,7 +146,7 @@ Hook-based agents rewrite Bash commands (e.g., `git status` -> `rtk git status`)

  Claude  --git status-->  shell  -->  git         Claude  --git status-->  RTK  -->  git
    ^                                   |            ^                      |          |
-    |        ~2,000 tokens (raw)        |            |   ~200 tokens        | filter   |
+    |         full raw output           |            |  compact output      | filter   |
    +-----------------------------------+            +------- (filtered) ---+----------+
 ```

@@ -144,9 +159,11 @@ Four strategies applied per command type:

 ## Commands

+> Percentages below are **reductions in bash output**, not reductions in your bill. See [How Savings Work](#how-savings-work).
+
 ### Files
 ```bash
-rtk ls .                        # Token-optimized directory tree
+rtk ls .                        # Compact directory tree
 rtk read file.rs                # Smart file reading
 rtk read file.rs -l aggressive  # Signatures only (strips bodies)
 rtk smart file.rs               # 2-line heuristic code summary
@@ -279,7 +296,7 @@ rtk session                     # Show RTK adoption across recent sessions
 ## Global Flags

 ```bash
-u, --ultra-compact    # ASCII icons, inline format (extra token savings)
+-u, --ultra-compact    # ASCII icons, inline format (further output reduction)
 -v, --verbose          # Increase verbosity (-v, -vv, -vvv)
 ```

@@ -287,7 +304,7 @@ rtk session                     # Show RTK adoption across recent sessions

 **Directory listing:**
 ```
-# ls -la (45 lines, ~800 tokens)        # rtk ls (12 lines, ~150 tokens)
+# ls -la (45 lines)                     # rtk ls (12 lines)
 drwxr-xr-x  15 user staff 480 ...       my-project/
 -rw-r--r--   1 user staff 1234 ...       +-- src/ (8 files)
 ...                                      |   +-- main.rs
@@ -296,7 +313,7 @@ drwxr-xr-x  15 user staff 480 ...       my-project/

 **Git operations:**
 ```
-# git push (15 lines, ~200 tokens)       # rtk git push (1 line, ~10 tokens)
+# git push (15 lines)                    # rtk git push (1 line)
 Enumerating objects: 5, done.             ok main
 Counting objects: 100% (5/5), done.
 Delta compression using up to 8 threads
@@ -316,7 +333,7 @@ test utils::test_format ... ok              test_overflow: panic at utils.rs:18

 The most effective way to use rtk. The hook transparently intercepts Bash commands and rewrites them to rtk equivalents before execution.

-**Result**: 100% rtk adoption across all conversations and subagents, zero token overhead.
+**Result**: 100% rtk adoption across all conversations and subagents, with no per-command context overhead.

 **Scope note:** this only applies to Bash tool calls. Claude Code built-in tools such as `Read`, `Grep`, and `Glob` bypass the hook, so use shell commands or explicit `rtk` commands when you want RTK filtering there.

@@ -370,7 +387,7 @@ rtk init -g

 ## Supported AI Tools

-RTK supports 15 AI coding tools. Each integration rewrites shell commands to `rtk` equivalents for 60-90% token savings where the agent supports command interception.
+RTK supports 15 AI coding tools. Each integration rewrites shell commands to `rtk` equivalents, reducing the bash output the agent reads where the agent supports command interception.

 | Tool | Install | Method |
 |------|---------|--------|
@@ -442,14 +459,14 @@ RTK can collect **anonymous, aggregate usage metrics** once per day. Telemetry i
 |----------|------|-----|
 | Identity | Salted device hash (SHA-256, not reversible) | Count unique installations without tracking individuals |
 | Environment | RTK version, OS, architecture, install method | Know which platforms to support and test |
-| Usage volume | Command count (24h), total commands, tokens saved (24h/30d/total) | Measure adoption and value delivered |
-| Quality | Top 5 passthrough commands (0% savings), parse failure count, commands with <30% savings | Identify missing filters and weak ones to improve |
+| Usage volume | Command count (24h), total commands, estimated tokens saved (24h/30d/total) | Measure adoption and value delivered |
+| Quality | Top 5 passthrough commands (0% reduction), parse failure count, commands with <30% reduction | Identify missing filters and weak ones to improve |
 | Ecosystem | Command category distribution (e.g. git 45%, cargo 20%, js 15%) | Prioritize filter development for popular ecosystems |
 | Retention | Days since first use, active days in last 30 | Understand engagement and detect churn |
 | Adoption | AI agent hook type (claude/gemini/codex), custom TOML filter count | Track integration coverage and DSL adoption |
 | Configuration | Whether config.toml exists, number of excluded commands, project count | Understand user maturity and customization patterns |
 | Features | Usage counts for meta-commands (gain, discover, proxy, verify) | Know which RTK features are valued vs unused |
-| Economics | Estimated USD savings (based on API token pricing) | Quantify the value RTK provides to users |
+| Economics | Estimated USD value, derived from the estimated tokens saved and a fixed internal constant | Quantify the value RTK provides to users |

 All data is **aggregate counts or anonymized command names** (first 3 words, no arguments). Top commands report only tool names (e.g. "git", "cargo"), never full command lines.

@@ -3,7 +3,7 @@
 </p>

 <p align="center">
-  <strong>Proxy CLI de alto rendimiento que reduce el consumo de tokens LLM en un 60-90%</strong>
+  <strong>Proxy CLI de alto rendimiento que elimina hasta el 90% de la salida bash que lee tu agente</strong>
 </p>

 <p align="center">
@@ -35,16 +35,40 @@

 rtk filtra y comprime las salidas de comandos antes de que lleguen al contexto de tu LLM. Binario Rust unico, cero dependencias, <10ms de overhead.

-## Ahorro de tokens (sesion de 30 min en Claude Code)
+## Que hace RTK

-| Operacion | Frecuencia | Estandar | rtk | Ahorro |
-|-----------|------------|----------|-----|--------|
-| `ls` / `tree` | 10x | 2,000 | 400 | -80% |
-| `cat` / `read` | 20x | 40,000 | 12,000 | -70% |
-| `grep` / `rg` | 8x | 16,000 | 3,200 | -80% |
-| `git status` | 10x | 3,000 | 600 | -80% |
-| `cargo test` / `npm test` | 5x | 25,000 | 2,500 | -90% |
-| **Total** | | **~118,000** | **~23,900** | **-80%** |
+RTK intercepta comandos de shell y comprime su salida antes de que tu agente la lea.
+
+| Operacion | Que hace RTK con la salida |
+|-----------|----------------------------|
+| `ls` / `tree` | Formato de arbol con conteo de archivos en lugar de una linea por entrada |
+| `cat` / `read` | Lectura inteligente: firmas y estructura en vez de cuerpos completos |
+| `grep` / `rg` | Trunca lineas largas, agrupa coincidencias por archivo |
+| `git status` | Formato stat compacto, agrupado por estado |
+| `git diff` | Contexto reducido, cabeceras eliminadas |
+| `git log` | Solo hash, autor y asunto |
+| `git add/commit/push` | Linea de confirmacion en lugar de la salida de progreso completa |
+| `cargo test` / `npm test` | Solo fallos, los tests que pasan se reducen a un contador |
+| `ruff check` | Agrupado por regla y archivo |
+| `pytest` | Solo fallos, traceback recortado |
+| `go test` | NDJSON parseado, solo fallos |
+| `docker ps` | Solo campos esenciales |
+
+## Como funciona el ahorro
+
+RTK elimina **hasta el 90% de la salida bash** que lee tu agente. Eso es lo que RTK mide, y no es lo mismo que reducir tu factura en un 90%.
+
+```
+Bytes de salida bash  ->  Tokens de entrada  ->  Coste
+ lo que RTK filtra        una fuente de entrada   tokens de entrada
+                          entre varias            + tokens de salida
+```
+
+La salida bash es **uno de los factores que alimentan los tokens de entrada**, junto con tu prompt, el prompt del sistema y el historial de conversacion. Los tokens de entrada son a su vez **solo una parte de la factura**, que tambien cuenta los tokens de salida. La reduccion se diluye en cada paso.
+
+Los recuentos de tokens que reporta RTK se estiman como `bytes / 4`: RTK no incluye ningun tokenizador, por lo que los **porcentajes son fiables pero las cifras absolutas de tokens son aproximadas**.
+
+> Explicacion completa: [Como funciona el ahorro en RTK](docs/guide/resources/savings-explained.md)

 ## Instalacion

@@ -103,6 +127,8 @@ Cuatro estrategias:

 ## Comandos

+> Los porcentajes de abajo son **reducciones de bytes de salida bash**, medidas con el estimador `bytes / 4` de RTK. Ver [Como funciona el ahorro](#como-funciona-el-ahorro).
+
 ### Archivos
 ```bash
 rtk ls .                        # Arbol de directorios optimizado
@@ -3,7 +3,7 @@
 </p>

 <p align="center">
-  <strong>Proxy CLI haute performance qui reduit la consommation de tokens LLM de 60-90%</strong>
+  <strong>Proxy CLI haute performance qui elimine jusqu'a 90% de la sortie bash lue par votre agent</strong>
 </p>

 <p align="center">
@@ -35,21 +35,40 @@

 rtk filtre et compresse les sorties de commandes avant qu'elles n'atteignent le contexte de votre LLM. Binaire Rust unique, zero dependance, <10ms d'overhead.

-## Economies de tokens (session Claude Code de 30 min)
+## Ce que fait RTK

-| Operation | Frequence | Standard | rtk | Economies |
-|-----------|-----------|----------|-----|-----------|
-| `ls` / `tree` | 10x | 2 000 | 400 | -80% |
-| `cat` / `read` | 20x | 40 000 | 12 000 | -70% |
-| `grep` / `rg` | 8x | 16 000 | 3 200 | -80% |
-| `git status` | 10x | 3 000 | 600 | -80% |
-| `git diff` | 5x | 10 000 | 2 500 | -75% |
-| `git log` | 5x | 2 500 | 500 | -80% |
-| `git add/commit/push` | 8x | 1 600 | 120 | -92% |
-| `cargo test` / `npm test` | 5x | 25 000 | 2 500 | -90% |
-| **Total** | | **~118 000** | **~23 900** | **-80%** |
+RTK intercepte les commandes shell et compresse leur sortie avant que votre agent ne la lise.

-> Estimations basees sur des projets TypeScript/Rust de taille moyenne.
+| Operation | Ce que RTK fait de la sortie |
+|-----------|------------------------------|
+| `ls` / `tree` | Format arborescent avec compteurs de fichiers au lieu d'une ligne par entree |
+| `cat` / `read` | Lecture intelligente : signatures et structure plutot que corps complets |
+| `grep` / `rg` | Tronque les lignes longues, regroupe les correspondances par fichier |
+| `git status` | Format stat compact, regroupe par etat |
+| `git diff` | Contexte reduit, en-tetes supprimes |
+| `git log` | Hash, auteur et sujet uniquement |
+| `git add/commit/push` | Ligne de confirmation au lieu de la sortie de progression complete |
+| `cargo test` / `npm test` | Echecs uniquement, tests reussis reduits a un compteur |
+| `ruff check` | Regroupe par regle et par fichier |
+| `pytest` | Echecs uniquement, traceback raccourci |
+| `go test` | NDJSON parse, echecs uniquement |
+| `docker ps` | Champs essentiels uniquement |
+
+## Comment fonctionnent les economies
+
+RTK elimine **jusqu'a 90% de la sortie bash** que votre agent lit. C'est cela que RTK mesure, et ce n'est pas la meme chose que reduire votre facture de 90%.
+
+```
+Octets de sortie bash  ->  Tokens d'entree  ->  Cout
+ ce que RTK filtre         une source d'entree   tokens d'entree
+                           parmi plusieurs       + tokens de sortie
+```
+
+La sortie bash est **un contributeur parmi d'autres aux tokens d'entree**, aux cotes de votre prompt, du prompt systeme et de l'historique de conversation. Les tokens d'entree ne sont eux-memes **qu'une partie de la facture**, qui compte aussi les tokens de sortie. La reduction se dilue a chaque etape.
+
+Les nombres de tokens rapportes par RTK sont estimes avec `octets / 4` : RTK n'embarque aucun tokenizer, donc les **pourcentages sont fiables mais les valeurs absolues en tokens restent approximatives**.
+
+> Explication complete : [Comment fonctionnent les economies RTK](docs/guide/resources/savings-explained.md)

 ## Installation

@@ -113,6 +132,8 @@ Quatre strategies appliquees par type de commande :

 ## Commandes

+> Les pourcentages ci-dessous sont des **reductions d'octets de sortie bash**, mesurees avec l'estimateur `octets / 4` de RTK. Voir [Comment fonctionnent les economies](#comment-fonctionnent-les-economies).
+
 ### Fichiers
 ```bash
 rtk ls .                        # Arbre de repertoires optimise
@@ -3,7 +3,7 @@
 </p>

 <p align="center">
-  <strong>LLM トークン消費を 60-90% 削減する高性能 CLI プロキシ</strong>
+  <strong>エージェントが読む bash 出力を最大 90% 削減する高性能 CLI プロキシ</strong>
 </p>

 <p align="center">
@@ -35,16 +35,40 @@

 rtk はコマンド出力を LLM コンテキストに届く前にフィルタリング・圧縮します。単一の Rust バイナリ、依存関係ゼロ、オーバーヘッド 10ms 未満。

-## トークン節約（30分の Claude Code セッション）
+## RTK がすること

-| 操作 | 頻度 | 標準 | rtk | 節約 |
-|------|------|------|-----|------|
-| `ls` / `tree` | 10x | 2,000 | 400 | -80% |
-| `cat` / `read` | 20x | 40,000 | 12,000 | -70% |
-| `grep` / `rg` | 8x | 16,000 | 3,200 | -80% |
-| `git status` | 10x | 3,000 | 600 | -80% |
-| `cargo test` / `npm test` | 5x | 25,000 | 2,500 | -90% |
-| **合計** | | **~118,000** | **~23,900** | **-80%** |
+RTK はシェルコマンドを横取りし、エージェントが読む前にその出力を圧縮します。
+
+| 操作 | RTK が出力に対して行うこと |
+|------|----------------------------|
+| `ls` / `tree` | 1 エントリ 1 行ではなく、ファイル数付きのツリー形式 |
+| `cat` / `read` | スマートなファイル読み取り：本文全体ではなくシグネチャと構造 |
+| `grep` / `rg` | 長い行を切り詰め、マッチをファイル単位でグループ化 |
+| `git status` | コンパクトな stat 形式、状態ごとにグループ化 |
+| `git diff` | コンテキストを削減、ヘッダーを除去 |
+| `git log` | ハッシュ、作者、件名のみ |
+| `git add/commit/push` | 進捗出力全体の代わりに確認行 1 行 |
+| `cargo test` / `npm test` | 失敗のみ、成功したテストは件数に集約 |
+| `ruff check` | ルールとファイルごとにグループ化 |
+| `pytest` | 失敗のみ、トレースバックを短縮 |
+| `go test` | NDJSON をパースし、失敗のみ |
+| `docker ps` | 必須フィールドのみ |
+
+## 節約の仕組み
+
+RTK はエージェントが読む **bash 出力を最大 90% 削減**します。これが RTK の測定対象であり、請求額が 90% 減ることと同じではありません。
+
+```
+bash 出力のバイト数  ->  入力トークン  ->  コスト
+ RTK がフィルタする部分   複数ある入力元      入力トークン
+                          のひとつ            + 出力トークン
+```
+
+bash 出力は、あなたのプロンプト、システムプロンプト、会話履歴と並ぶ**入力トークンの構成要素のひとつ**にすぎません。そして入力トークン自体も、出力トークンを含む**請求額の一部**でしかありません。削減効果は各段階で薄まります。
+
+RTK が報告するトークン数は `バイト数 / 4` で見積もられています。RTK はトークナイザーを同梱していないため、**割合は信頼できますが、トークンの絶対値はあくまで概算**です。
+
+> 詳しい解説：[RTK の節約の仕組み](docs/guide/resources/savings-explained.md)

 ## インストール

@@ -103,6 +127,8 @@ git status  # 自動的に rtk git status に書き換え

 ## コマンド

+> 以下の割合は **bash 出力バイト数の削減率**であり、RTK の `バイト数 / 4` 推定器で測定しています。[節約の仕組み](#節約の仕組み)を参照してください。
+
 ### ファイル
 ```bash
 rtk ls .                        # 最適化されたディレクトリツリー
@@ -3,7 +3,7 @@
 </p>

 <p align="center">
-  <strong>LLM 토큰 소비를 60-90% 줄이는 고성능 CLI 프록시</strong>
+  <strong>에이전트가 읽는 bash 출력을 최대 90% 줄이는 고성능 CLI 프록시</strong>
 </p>

 <p align="center">
@@ -35,16 +35,40 @@

 rtk는 명령 출력이 LLM 컨텍스트에 도달하기 전에 필터링하고 압축합니다. 단일 Rust 바이너리, 의존성 없음, 10ms 미만의 오버헤드.

-## 토큰 절약 (30분 Claude Code 세션)
+## RTK가 하는 일

-| 작업 | 빈도 | 표준 | rtk | 절약 |
-|------|------|------|-----|------|
-| `ls` / `tree` | 10x | 2,000 | 400 | -80% |
-| `cat` / `read` | 20x | 40,000 | 12,000 | -70% |
-| `grep` / `rg` | 8x | 16,000 | 3,200 | -80% |
-| `git status` | 10x | 3,000 | 600 | -80% |
-| `cargo test` / `npm test` | 5x | 25,000 | 2,500 | -90% |
-| **합계** | | **~118,000** | **~23,900** | **-80%** |
+RTK는 셸 명령을 가로채 에이전트가 읽기 전에 출력을 압축합니다.
+
+| 작업 | RTK가 출력에 하는 일 |
+|------|----------------------|
+| `ls` / `tree` | 항목당 한 줄 대신 파일 개수가 포함된 트리 형식 |
+| `cat` / `read` | 스마트 파일 읽기: 전체 본문 대신 시그니처와 구조 |
+| `grep` / `rg` | 긴 줄을 잘라내고 매치를 파일별로 그룹화 |
+| `git status` | 컴팩트한 stat 형식, 상태별 그룹화 |
+| `git diff` | 컨텍스트 축소, 헤더 제거 |
+| `git log` | 해시, 작성자, 제목만 |
+| `git add/commit/push` | 전체 진행 출력 대신 확인 한 줄 |
+| `cargo test` / `npm test` | 실패만 표시, 통과한 테스트는 개수로 축약 |
+| `ruff check` | 규칙과 파일별로 그룹화 |
+| `pytest` | 실패만 표시, 트레이스백 축약 |
+| `go test` | NDJSON 파싱, 실패만 표시 |
+| `docker ps` | 핵심 필드만 |
+
+## 절약이 계산되는 방식
+
+RTK는 에이전트가 읽는 **bash 출력을 최대 90%** 줄입니다. 이것이 RTK가 측정하는 값이며, 요금이 90% 줄어드는 것과는 다릅니다.
+
+```
+bash 출력 바이트  ->  입력 토큰  ->  비용
+ RTK가 거르는 부분     여러 입력원 중       입력 토큰
+                       하나                 + 출력 토큰
+```
+
+bash 출력은 프롬프트, 시스템 프롬프트, 대화 기록과 함께 **입력 토큰을 구성하는 요소 중 하나**입니다. 그리고 입력 토큰 역시 출력 토큰까지 포함하는 **요금의 일부일 뿐**입니다. 감소 효과는 각 단계에서 희석됩니다.
+
+RTK가 보고하는 토큰 수는 `바이트 / 4`로 추정됩니다. RTK에는 토크나이저가 포함되어 있지 않으므로 **비율은 신뢰할 수 있지만 토큰 절대값은 근사치**입니다.
+
+> 전체 설명: [RTK의 절약이 계산되는 방식](docs/guide/resources/savings-explained.md)

 ## 설치

@@ -103,6 +127,8 @@ git status  # 자동으로 rtk git status로 재작성

 ## 명령어

+> 아래 백분율은 RTK의 `바이트 / 4` 추정기로 측정한 **bash 출력 바이트 감소율**입니다. [절약이 계산되는 방식](#절약이-계산되는-방식)을 참조하세요.
+
 ### 파일
 ```bash
 rtk ls .                        # 최적화된 디렉토리 트리
@@ -3,7 +3,7 @@
 </p>

 <p align="center">
-  <strong>Proxy CLI de alta performance que reduz o consumo de tokens LLM em 60-90%</strong>
+  <strong>Proxy CLI de alta performance que corta até 90% da saída bash que seu agente lê</strong>
 </p>

 <p align="center">
@@ -36,16 +36,40 @@

 rtk filtra e comprime saídas de comandos antes de chegarem ao contexto do seu LLM. Binário Rust único, zero dependências, overhead inferior a 10ms.

-## Economia de tokens (sessão de 30 min no Claude Code)
+## O que o RTK faz

-| Operação | Frequência | Padrão | rtk | Economia |
-|-----------|------------|----------|-----|--------|
-| `ls` / `tree` | 10x | 2,000 | 400 | -80% |
-| `cat` / `read` | 20x | 40,000 | 12,000 | -70% |
-| `grep` / `rg` | 8x | 16,000 | 3,200 | -80% |
-| `git status` | 10x | 3,000 | 600 | -80% |
-| `cargo test` / `npm test` | 5x | 25,000 | 2,500 | -90% |
-| **Total** | | **~118,000** | **~23,900** | **-80%** |
+O RTK intercepta comandos de shell e comprime a saída antes que seu agente a leia.
+
+| Operação | O que o RTK faz com a saída |
+|-----------|-----------------------------|
+| `ls` / `tree` | Formato de árvore com contagem de arquivos em vez de uma linha por entrada |
+| `cat` / `read` | Leitura inteligente: assinaturas e estrutura em vez de corpos completos |
+| `grep` / `rg` | Trunca linhas longas, agrupa correspondências por arquivo |
+| `git status` | Formato stat compacto, agrupado por estado |
+| `git diff` | Contexto reduzido, cabeçalhos removidos |
+| `git log` | Apenas hash, autor e assunto |
+| `git add/commit/push` | Linha de confirmação em vez da saída de progresso completa |
+| `cargo test` / `npm test` | Apenas falhas, testes aprovados reduzidos a um contador |
+| `ruff check` | Agrupado por regra e arquivo |
+| `pytest` | Apenas falhas, traceback encurtado |
+| `go test` | NDJSON parseado, apenas falhas |
+| `docker ps` | Apenas campos essenciais |
+
+## Como funciona a economia
+
+O RTK corta **até 90% da saída bash** que seu agente lê. É isso que o RTK mede, e não é a mesma coisa que reduzir sua fatura em 90%.
+
+```
+Bytes de saída bash  ->  Tokens de entrada  ->  Custo
+ o que o RTK filtra      uma fonte de entrada    tokens de entrada
+                         entre várias            + tokens de saída
+```
+
+A saída bash é **um dos contribuintes para os tokens de entrada**, ao lado do seu prompt, do prompt de sistema e do histórico da conversa. Os tokens de entrada são, por sua vez, **apenas parte da fatura**, que também conta os tokens de saída. A redução se dilui a cada etapa.
+
+As contagens de tokens que o RTK reporta são estimadas como `bytes / 4`: o RTK não embarca nenhum tokenizador, portanto os **percentuais são confiáveis, mas os números absolutos de tokens são aproximados**.
+
+> Explicação completa: [Como funciona a economia do RTK](docs/guide/resources/savings-explained.md)

 ## Instalacao

@@ -104,6 +128,8 @@ Quatro estratégias:

 ## Comandos

+> Os percentuais abaixo são **reduções de bytes da saída bash**, medidas com o estimador `bytes / 4` do RTK. Veja [Como funciona a economia](#como-funciona-a-economia).
+
 ### Arquivos
 ```bash
 rtk ls .                        # Árvore de diretórios otimizada
@@ -3,7 +3,7 @@
 </p>

 <p align="center">
-  <strong>高性能 CLI 代理，将 LLM token 消耗降低 60-90%</strong>
+  <strong>高性能 CLI 代理，为你的智能体削减多达 90% 的 bash 输出</strong>
 </p>

 <p align="center">
@@ -35,17 +35,40 @@

 rtk 在命令输出到达 LLM 上下文之前进行过滤和压缩。单一 Rust 二进制文件，零依赖，<10ms 开销。

-## Token 节省（30 分钟 Claude Code 会话）
+## RTK 做什么

-| 操作 | 频率 | 标准 | rtk | 节省 |
-|------|------|------|-----|------|
-| `ls` / `tree` | 10x | 2,000 | 400 | -80% |
-| `cat` / `read` | 20x | 40,000 | 12,000 | -70% |
-| `grep` / `rg` | 8x | 16,000 | 3,200 | -80% |
-| `git status` | 10x | 3,000 | 600 | -80% |
-| `git diff` | 5x | 10,000 | 2,500 | -75% |
-| `cargo test` / `npm test` | 5x | 25,000 | 2,500 | -90% |
-| **总计** | | **~118,000** | **~23,900** | **-80%** |
+RTK 拦截 shell 命令，在你的智能体读取之前压缩其输出。
+
+| 操作 | RTK 对输出做了什么 |
+|------|--------------------|
+| `ls` / `tree` | 用带文件计数的树形格式代替每个条目一行 |
+| `cat` / `read` | 智能文件读取：保留签名和结构，而非完整函数体 |
+| `grep` / `rg` | 截断超长行，按文件分组匹配结果 |
+| `git status` | 紧凑的 stat 格式，按状态分组 |
+| `git diff` | 减少上下文，去掉头部信息 |
+| `git log` | 仅保留哈希、作者和标题 |
+| `git add/commit/push` | 用一行确认代替完整的进度输出 |
+| `cargo test` / `npm test` | 仅显示失败，通过的测试折叠为计数 |
+| `ruff check` | 按规则和文件分组 |
+| `pytest` | 仅显示失败，精简 traceback |
+| `go test` | 解析 NDJSON，仅显示失败 |
+| `docker ps` | 仅保留关键字段 |
+
+## 节省是如何计算的
+
+RTK 为你的智能体削减**多达 90% 的 bash 输出**。这正是 RTK 所测量的指标，它与「账单降低 90%」不是一回事。
+
+```
+bash 输出字节数  ->  输入 token  ->  费用
+ RTK 过滤的部分      多个输入来源       输入 token
+                     之一               + 输出 token
+```
+
+bash 输出只是**输入 token 的来源之一**，此外还有你的提示词、系统提示词和对话历史。而输入 token 本身也**只是账单的一部分**，账单还包含输出 token。削减效果在每一步都会被稀释。
+
+RTK 报告的 token 数量按 `字节数 / 4` 估算：RTK 不内置分词器，因此**百分比是可靠的，但 token 绝对数值只是近似值**。
+
+> 完整说明：[RTK 的节省是如何计算的](docs/guide/resources/savings-explained.md)

 ## 安装

@@ -104,6 +127,8 @@ git status  # 自动重写为 rtk git status

 ## 命令

+> 下列百分比是 **bash 输出字节数的削减比例**，由 RTK 的 `字节数 / 4` 估算器测得。参见[节省是如何计算的](#节省是如何计算的)。
+
 ### 文件
 ```bash
 rtk ls .                        # 优化的目录树
@@ -14,7 +14,7 @@ RTK supports 100+ commands across 15+ ecosystems. Without telemetry, we have no
 - Which commands are used most and need the best filters
 - Which filters are underperforming and need improvement
 - Which ecosystems to prioritize for new filter development
- How much value RTK delivers to users (token savings in $ terms)
+- How much bash output RTK removes before it reaches the model
 - Whether users stay engaged over time or churn after trying RTK

 This data directly drives our roadmap. For example, if telemetry shows that 40% of users run Python commands but only 10% of our filters cover Python, we know where to invest next.
@@ -60,9 +60,9 @@ This data directly drives our roadmap. For example, if telemetry shows that 40%

 | Field | Example | Purpose |
 |-------|---------|---------|
-| `passthrough_top` | `["git:15", "npm:8"]` | Top 5 commands with 0% savings — these need filters |
+| `passthrough_top` | `["git:15", "npm:8"]` | Top 5 commands with 0% bash output reduction — these need filters |
 | `parse_failures_24h` | `3` | Filter fragility — high count means filters are breaking |
-| `low_savings_commands` | `["rtk docker ps:25%"]` | Commands averaging <30% savings — filters to improve |
+| `low_savings_commands` | `["rtk <cmd>:25%"]` | Commands averaging <30% bash output reduction — filters to improve. The example is a placeholder, not a measured value |
 | `avg_savings_per_command` | `68.5` | Unweighted average (vs global which is volume-biased) |

 ### Ecosystem distribution
@@ -83,7 +83,7 @@ This data directly drives our roadmap. For example, if telemetry shows that 40%
 | Field | Example | Purpose |
 |-------|---------|---------|
 | `tokens_saved_30d` | `12000000` | 30-day token savings for trend analysis |
-| `estimated_savings_usd_30d` | `36.0` | Estimated dollar value saved (at ~$3/Mtok input pricing, Claude Sonnet) |
+| `estimated_savings_usd_30d` | — | A USD value derived from the estimated tokens saved and a fixed internal constant. It is not a measured cost and does not reflect any provider's pricing |

 ### Adoption

@@ -161,10 +161,10 @@ Database: ~/.local/share/rtk/history.db

 > For the full file-level module tree, see [TECHNICAL.md](TECHNICAL.md#4-folder-map) and each folder's README.

-**Token savings by ecosystem:**
+**Bash output reduction by ecosystem** (percentages are shell output, not billed tokens):

 ```
-Savings by ecosystem:
+Bash output reduction by ecosystem:
  GIT (cmds/git/)          85-99%    status, diff, log, gh, gt
  JS/TS (cmds/js/)         70-99%    lint, tsc, next, prettier, playwright, prisma, vitest, pnpm
  PYTHON (cmds/python/)    70-90%    ruff, pytest, mypy, pip
@@ -325,6 +325,8 @@ fn calculate_total(items: &[Item]) -> i32 {
 fn calculate_total(items: &[Item]) -> i32 { ... }
 ```

+The percentages above are reductions in the emitted output bytes, not in billed tokens.
+
 **Language Support**: Rust, Python, JavaScript, TypeScript, Go, C, C++, Java

 **Detection**: File extension-based with fallback heuristics
@@ -711,7 +713,7 @@ Flow:
   FROM commands
   WHERE timestamp > datetime('now', '-90 days')

-   Output:
+   Output (illustrative mock, not measured results):
   ┌──────────────────────────────────────┐
   │ Token Savings Report (90 days)      │
   ├──────────────────────────────────────┤
@@ -728,6 +730,10 @@ Flow:

   Note: Time column shows average execution
   duration per command (added in v0.7.1)
+   The 78.5% / 45,678 figures above are placeholder
+   values for layout, not benchmark results.
+   savings_pct measures bash output bytes; token
+   counts are bytes/4 estimates, not billed tokens.
 ```

 ### Thread Safety
@@ -903,7 +909,7 @@ Write template:
 │ - rtk lint                          │
 │ - rtk test                          │
 │                                     │
-│ Benefits: 60-90% token reduction    │
+│ Benefits: 60-90% less bash output   │
 └─────────────────────────────────────┘
      ↓
 Success: "✓ Initialized rtk for LLM integration"
@@ -138,7 +138,7 @@ For the full error-handling architecture (propagation chain, exit code preservat
 See [`CONTRIBUTING.md` — Testing](../../CONTRIBUTING.md#testing) for the full strategy. In short, for a new filter you typically want:

 - **Unit + snapshot tests** in the same file, using the `insta` crate.
- **A token-savings assertion** verifying the filter hits the ≥60% target on a real fixture.
+- **A savings assertion** verifying the filter hits the ≥60% target on a real fixture. The target is a reduction in bash output, measured with RTK's token estimator rather than a real tokenizer; see [How RTK Savings Work](../guide/resources/savings-explained.md).

 Minimal example:

@@ -162,7 +162,7 @@ mod tests {
        let input = include_str!("../../../tests/fixtures/git_log_raw.txt");
        let output = filter_git_log(input);
        let savings = 100.0 - (count_tokens(&output) as f64 / count_tokens(input) as f64 * 100.0);
-        assert!(savings >= 60.0, "expected ≥60% savings, got {:.1}%", savings);
+        assert!(savings >= 60.0, "expected ≥60% output reduction, got {:.1}%", savings);
    }
 }
 ```
@@ -12,7 +12,9 @@

 LLM-powered coding agents (Claude Code, Copilot, Cursor, etc.) consume tokens for every CLI command output they process. Most command outputs contain boilerplate, progress bars, ANSI escape codes, and verbose formatting that wastes tokens without providing actionable information.

-RTK sits between the agent and the CLI, filtering outputs to keep only what matters. This achieves 60-90% token savings per command, reducing costs and increasing effective context window utilization. RTK is a single Rust binary with no runtime dependencies beyond the compiled binary itself, adding less than 10ms overhead per command.
+RTK sits between the agent and the CLI, filtering outputs to keep only what matters. This cuts 60-90% of the bash output per command, reducing costs and increasing effective context window utilization. RTK is a single Rust binary with no runtime dependencies beyond the compiled binary itself, adding less than 10ms overhead per command.
+
+Every percentage below measures **bash output**, which is one contributor to input tokens, themselves only part of a bill that also counts output tokens. RTK ships no tokenizer (`src/core/tracking.rs` estimates `bytes / 4`), so the ratios are reliable but the absolute token counts are approximate. See [How RTK Savings Work](../guide/resources/savings-explained.md).

 ---

@@ -246,7 +248,7 @@ When Clap parsing fails (unknown command):
 1. Guard: check if the command is an RTK meta-command (`gain`, `init`, etc.) -- if so, show Clap error
 2. Look up TOML DSL filters via `toml_filter::find_matching_filter()`
 3. If TOML match: capture stdout, apply filter pipeline, track savings
-4. If no match: pure passthrough with `Stdio::inherit`, track as 0% savings
+4. If no match: pure passthrough with `Stdio::inherit`, track as 0% output reduction

 ```
 Command received
@@ -255,7 +257,7 @@ Command received
     -> No:  run_fallback()
              -> TOML filter match?
                 -> Yes: Capture stdout, apply filter, track savings
-                 -> No:  Passthrough (inherit stdio, track 0% savings)
+                 -> No:  Passthrough (inherit stdio, track 0% reduction)
 ```

 > **Details**: [`src/core/README.md`](../src/core/README.md) covers the TOML filter engine, filter pipeline stages, and trust-gated project filters.
@@ -344,7 +346,7 @@ RTK supports the following LLM agents through hook integrations:

 ### Rust Filters (cmds/**)

-Compiled filter modules for complex transformations with 60-95% token savings.
+Compiled filter modules for complex transformations, cutting 60-95% of the bash output.

 > **Details**: [`src/cmds/README.md`](../src/cmds/README.md) and each ecosystem subdirectory README.

@@ -363,7 +365,7 @@ Declarative filters with an 8-stage pipeline: strip ANSI, regex replace, match o
 | Startup time | < 10ms | `hyperfine 'rtk git status' 'git status'` |
 | Memory usage | < 5MB resident | `/usr/bin/time -v rtk git status` |
 | Binary size | < 5MB stripped | `ls -lh target/release/rtk` |
-| Token savings | 60-90% per filter | Snapshot + token count tests |
+| Bash output reduction | 60-90% per filter | Snapshot + token count tests |

 Achieved through:
 - Zero async overhead (single-threaded, no tokio)
@@ -395,7 +397,7 @@ fn test_my_filter() {
 }
 ```

-**3. Verify token savings** (60% minimum required):
+**3. Verify the output reduction** (>=60% of the bash output required; `count_tokens` in tests and the `bytes / 4` estimator behind `rtk gain` are both approximations, reliable as ratios):
 ```rust
 #[test]
 fn test_my_filter_savings() {
@@ -9,7 +9,7 @@ sidebar:

 ## rtk discover — find missed savings

-`rtk discover` analyzes your Claude Code command history to identify commands that ran without RTK filtering and calculates how many tokens you lost.
+`rtk discover` analyzes your Claude Code command history to identify commands that ran without RTK filtering, and estimates how much bash output RTK would have removed from them.

 ```bash
 rtk discover                    # analyze current project history
@@ -17,7 +17,7 @@ rtk discover --all              # all projects
 rtk discover --all --since 7    # last 7 days, all projects
 ```

-**Example output:**
+**Example output** (sample numbers, not typical results):

 ```
 Missed savings analysis (last 7 days)
@@ -32,6 +32,8 @@ Total missed:           23     ~66,000 tokens
 Run `rtk init --global` to capture these automatically.
 ```

+The `~N tokens` figures are **estimated bash output bytes divided by 4**, not tokens billed by your provider. RTK ships no real tokenizer, and bash output is only one contributor to input tokens. Read them as an order of magnitude of the output volume RTK could have compressed. See [How RTK Savings Work](../resources/savings-explained.md).
+
 If commands appear in the missed list after installing RTK, it usually means the hook isn't active for that agent. See [Troubleshooting](../resources/troubleshooting.md) — "Agent not using RTK".

 ## rtk session — adoption tracking
@@ -1,13 +1,23 @@
 ---
 title: Token Savings Analytics
-description: Measure and analyze your RTK token savings with rtk gain
+description: Measure and analyze the bash output reduction RTK achieves with rtk gain
 sidebar:
  order: 1
 ---

 # Token Savings Analytics

-`rtk gain` shows how many tokens RTK has saved across all your commands, with daily, weekly, and monthly breakdowns.
+`rtk gain` shows how much bash output RTK has removed across all your commands, with daily, weekly, and monthly breakdowns.
+
+What `rtk gain` measures is the reduction in **bash output bytes**, converted to estimated tokens:
+
+```
+Bash output bytes  ->  Input tokens  ->  Cost
+ what RTK filters      one input source     input + output tokens
+                       among several
+```
+
+Bash output is one contributor to input tokens, alongside your prompt, the system prompt and conversation history. Input tokens are in turn only part of the bill, which also counts output tokens. See [How RTK Savings Work](../resources/savings-explained.md) for the full picture.

 ## Quick reference

@@ -38,6 +48,8 @@ rtk gain --all --format csv  > savings.csv
 rtk gain --daily
 ```

+**Example output** (illustrative numbers from one machine, not typical results — yours depend entirely on which commands you run):
+
 ```
 📅 Daily Breakdown (3 days)
 ════════════════════════════════════════════════════════════════
@@ -51,10 +63,10 @@ TOTAL            196       1.3M      59.2K       1.2M   95.6%
 ```

 - **Cmds**: RTK commands executed
- **Input**: Estimated tokens from raw command output
- **Output**: Actual tokens after filtering
- **Saved**: Input - Output (tokens that never reached the LLM)
- **Save%**: Saved / Input × 100
+- **Input**: Estimated tokens from raw command output (`bytes / 4`)
+- **Output**: Estimated tokens after filtering (`bytes / 4`)
+- **Saved**: Input - Output, in estimated tokens
+- **Save%**: Saved / Input × 100 — a **bash output byte ratio**, not a share of your bill

 ## Weekly and monthly breakdowns

@@ -91,8 +103,8 @@ Same columns as daily, aggregated by Sunday-Saturday week or calendar month.

 ## Typical savings by command

-| Command | Typical savings | Mechanism |
-|---------|----------------|-----------|
+| Command | Bash output reduction | Mechanism |
+|---------|----------------------|-----------|
 | `git status` | 77-93% | Compact stat format |
 | `eslint` | 84% | Group by rule |
 | `jest` | 94-99% | Show failures only |
@@ -101,9 +113,11 @@ Same columns as daily, aggregated by Sunday-Saturday week or calendar month.
 | `pnpm list` | 70-90% | Compact dependencies |
 | `grep` | 70% | Truncate + group |

+These percentages measure bash output bytes removed, not cost reduction. See [How RTK Savings Work](../resources/savings-explained.md).
+
 ## How token estimation works

-RTK estimates tokens using `text.len() / 4` (4 characters per token average). This is accurate to ±10% compared to actual LLM tokenization — sufficient for trend analysis.
+`rtk gain` estimates tokens as `bytes / 4` (`src/core/tracking.rs:1284`). RTK ships no real tokenizer by design: embedding one would cost startup time and would require a tokenizer per model, or a per-session model lookup, which RTK does not implement. The same estimator is applied to raw and filtered output, so the percentage is reliable; the absolute token counts are approximate and will not match your provider's billing.

 ```
 Input Tokens  = estimate_tokens(raw_command_output)
@@ -179,7 +193,7 @@ jobs:

 ## Quota estimate

-`--quota` estimates how many tokens RTK has saved relative to your monthly subscription budget, so you can see the cost impact of those savings.
+`--quota` expresses the estimated tokens saved as a fraction of a monthly subscription budget. Like every other figure in `rtk gain`, it is derived from the `bytes / 4` estimate of bash output, so treat it as an order of magnitude rather than a billing forecast.

 ```bash
 rtk gain --quota          # uses 20x tier by default
@@ -114,7 +114,7 @@ RTK_DISABLED=1 git rebase main

 RTK sends one anonymous ping per day (23h interval). No personal data, no file paths, no command content.

-Data sent: device hash, version, OS, architecture, command count/24h, top commands, savings %.
+Data sent: device hash, version, OS, architecture, command count/24h, top commands, bash output reduction %.

 To opt out:

@@ -14,13 +14,13 @@ Two unrelated projects share the name `rtk`. Make sure you install the right one
 - **Rust Token Killer** (`rtk-ai/rtk`) — this project, a token-saving CLI proxy
 - **Rust Type Kit** (`reachingforthejack/rtk`) — a different tool for generating Rust types

-The easiest way to verify you have the correct one: run `rtk gain`. It should display token savings stats. If it returns "command not found", you either have the wrong package or RTK is not installed.
+The easiest way to verify you have the correct one: run `rtk gain`. It should display the savings dashboard. If it returns "command not found", you either have the wrong package or RTK is not installed.

 ## Check before installing

 ```bash
 rtk --version   # should print: rtk x.y.z
-rtk gain        # should show token savings stats
+rtk gain        # should show the savings dashboard
 ```

 If both commands work, RTK is already installed. Skip to [Project initialization](#project-initialization).
@@ -61,7 +61,7 @@ Download from [GitHub releases](https://github.com/rtk-ai/rtk/releases):

 ```bash
 rtk --version   # rtk x.y.z
-rtk gain        # token savings dashboard
+rtk gain        # savings dashboard
 ```

 If `rtk gain` fails but `rtk --version` succeeds, you installed Rust Type Kit by mistake. Uninstall it first:
@@ -1,6 +1,6 @@
 ---
 title: Quick Start
-description: Get RTK running in 5 minutes and see your first token savings
+description: Get RTK running in 5 minutes and see your first bash output reduction
 sidebar:
  order: 2
 ---
@@ -58,12 +58,14 @@ RTK covers all major ecosystems — Git, Cargo/Rust, JavaScript, Python, Go, Rub

 ## Step 3: Check your savings

-After a few commands, see how much was saved:
+After a few commands, see how much bash output was removed:

 ```bash
 rtk gain
 ```

+**Sample output** (illustrative, not a promise — your numbers depend on which commands you run):
+
 ```
 Total commands : 12
 Input tokens   : 45,230
@@ -71,6 +73,8 @@ Output tokens  : 4,890
 Saved          : 40,340  (89.2%)
 ```

+The token figures are estimates: RTK counts `bytes / 4`, not real tokenizer output. The percentage is a reduction in **bash output bytes**, which is one contributor to input tokens — not a percentage off your bill. See [How RTK Savings Work](../resources/savings-explained.md).
+
 ## Step 4: Unsupported commands

 Commands RTK doesn't recognize run through passthrough — output is unchanged, usage is tracked:
@@ -81,6 +85,7 @@ rtk proxy make install

 ## Next steps

- [What RTK Optimizes](../resources/what-rtk-covers.md) — all supported commands and savings by ecosystem
+- [What RTK Optimizes](../resources/what-rtk-covers.md) — all supported commands and bash output reduction by ecosystem
+- [How RTK Savings Work](../resources/savings-explained.md) — what the percentages actually measure
 - [Supported agents](./supported-agents.md) — Claude Code, Cursor, Copilot, and more
 - [Configuration](./configuration.md) — customize RTK behavior
@@ -11,7 +11,7 @@ RTK supports all major AI coding agents across 3 integration tiers. Mistral Vibe

 ## How it works

-Each agent integration intercepts CLI commands before execution and rewrites them to their RTK equivalent. The agent runs `rtk cargo test` instead of `cargo test`, sees filtered output, and uses up to 90% fewer tokens — without any change to your workflow.
+Each agent integration intercepts CLI commands before execution and rewrites them to their RTK equivalent. The agent runs `rtk cargo test` instead of `cargo test`, sees filtered output, and reads up to 90% fewer bash output bytes — without any change to your workflow.

 All rewrite logic lives in the RTK binary (`rtk rewrite`). Agent hooks are thin delegates that parse the agent-specific JSON format and call `rtk rewrite` for the actual decision.

@@ -21,7 +21,7 @@ Agent runs "cargo test"
  -> Calls rtk rewrite "cargo test"
  -> Returns "rtk cargo test"
  -> Agent executes filtered command
-  -> LLM sees 90% fewer tokens
+  -> LLM reads up to 90% fewer bash output bytes
 ```

 ## Supported agents
@@ -1,6 +1,6 @@
 ---
 title: RTK Documentation
-description: RTK (Rust Token Killer) — reduce LLM token consumption by 60-90% on common dev commands, with zero workflow changes
+description: RTK (Rust Token Killer) — cut up to 90% of the bash output your agent reads on common dev commands, with zero workflow changes
 sidebar:
  order: 1
 ---
@@ -9,7 +9,7 @@ sidebar:

 RTK is a CLI proxy that sits between your AI assistant and your development tools. It filters command output before it reaches the LLM, keeping only what matters and discarding boilerplate, progress bars, and noise.

-**Result:** 60-90% fewer tokens consumed per command, without changing how you work. You run `git status` as usual — RTK's hook intercepts it, filters the output, and the LLM sees a compact 3-line summary instead of 40 lines.
+**Result:** up to 90% fewer bash output bytes reaching the LLM per command, without changing how you work. You run `git status` as usual — RTK's hook intercepts it, filters the output, and the LLM sees a compact 3-line summary instead of 40 lines.

 ## How it works

@@ -21,16 +21,29 @@ Your AI assistant runs:  git status
              rtk git status  (transparent rewrite)
                              ↓
     Raw output: 40 lines     →     Filtered: 3 lines
-     ~800 tokens              →     ~60 tokens  (92% saved)
                              ↓
              LLM sees the compact output
 ```

 Zero config changes to your workflow. The hook handles everything automatically.

+## What the savings mean
+
+RTK reduces **bash output bytes** — the output a shell command sends back before your agent reads it. That is not the same as reducing your bill by the same amount:
+
+```
+Bash output bytes  ->  Input tokens  ->  Cost
+ what RTK filters      one input source     input + output tokens
+                       among several
+```
+
+Bash output is one contributor to input tokens, alongside your prompt, the system prompt and conversation history. Input tokens are in turn only part of the bill, which also counts output tokens. The reduction dilutes at every step.
+
+See [How RTK Savings Work](./resources/savings-explained.md) for the full picture, including why the token counts RTK reports are estimates.
+
 ## What RTK optimizes

-Dozens of commands across all major ecosystems — Git, Cargo/Rust, JavaScript, Python, Go, Ruby, .NET, Docker/Kubernetes, and more. See [What RTK Optimizes](./resources/what-rtk-covers.md) for the full list with savings percentages.
+Dozens of commands across all major ecosystems — Git, Cargo/Rust, JavaScript, Python, Go, Ruby, .NET, Docker/Kubernetes, and more. See [What RTK Optimizes](./resources/what-rtk-covers.md) for the full list with per-command bash output reduction.

 ## Get started

@@ -0,0 +1,94 @@
+---
+title: How RTK Savings Work
+description: What RTK actually reduces, how bash output savings translate into cost, and why the token counts are estimates
+sidebar:
+  order: 2
+---
+
+# How RTK Savings Work
+
+RTK cuts **up to 90% of the bash output** your agent reads. This page explains what that number measures, what it does not measure, and how it reaches your bill.
+
+## What RTK filters
+
+RTK sits between your agent and the CLI. When the agent runs a shell command, RTK executes it, compresses the output, and returns the compressed version.
+
+```
+agent runs a shell command
+        |
+        v
+   RTK filters the output
+        |
+        v
+  agent reads the result
+```
+
+The only thing RTK changes is **the bytes a shell command sends back**. Everything RTK reports as "savings" is measured on those bytes.
+
+## The savings chain
+
+```
+Bash output bytes  ->  Input tokens  ->  Cost
+ what RTK filters      one input source     input + output tokens
+                       among several
+```
+
+Those bytes are **one contributor to input tokens**, alongside your prompt, the system prompt, and conversation history. Input tokens are in turn **only part of the bill**, which also counts output tokens.
+
+So the reduction dilutes at every step: a large cut in bash output produces a smaller cut in input tokens, and a smaller one again in cost. A command showing 90% fewer output bytes does not make your session 90% cheaper.
+
+This is why RTK reports bash output reduction rather than a cost figure. Bash output is the part RTK controls; the rest depends on your prompt, your model, how much the agent writes back, and how much of the conversation is replayed on each call.
+
+## Why the token counts are estimates
+
+`rtk gain` estimates tokens as `bytes / 4`:
+
+```rust
+// src/core/tracking.rs
+pub fn estimate_tokens(text: &str) -> usize {
+    // ~4 chars per token on average
+    (text.len() as f64 / 4.0).ceil() as usize
+}
+```
+
+RTK ships **no real tokenizer** by design. Embedding one would cost startup time, and it would require a tokenizer per model, or a per-session model lookup, which RTK does not implement.
+
+The consequence is worth understanding:
+
+- **The percentage is reliable.** The same estimator is applied to the raw output and the filtered output, so the ratio between them holds regardless of the estimator's absolute accuracy.
+- **The absolute token counts are approximate.** They will not match your provider's billing. Treat `Input tokens: 45,230` as an order of magnitude, not an invoice line.
+
+If you need exact counts, run the raw and filtered output through your model's own tokenizer.
+
+### Two estimators, one caveat
+
+RTK uses different approximations in different places, and neither is a real tokenizer:
+
+| Where | Estimator | Used for |
+|-------|-----------|----------|
+| `rtk gain`, tracking, telemetry | `bytes / 4` (`src/core/tracking.rs`) | The savings dashboard and stored history |
+| Filter tests | `text.split_whitespace().count()` | The ≥60% reduction gate enforced in CI |
+
+They produce different absolute numbers from the same input. Both are applied identically to the raw and the filtered side, so both are sound as ratios — which is all either is used for.
+
+## How to read `rtk gain`
+
+| Column | What it actually is |
+|--------|---------------------|
+| Input | Estimated tokens from raw command output, `bytes / 4` |
+| Output | Estimated tokens after filtering, `bytes / 4` |
+| Saved | Input minus Output, in estimated tokens |
+| Save% | Reduction in bash output bytes |
+
+`Save%` is the meaningful number. It is a byte ratio, and it is accurate as a ratio.
+
+## What RTK does not reduce
+
+- **Output tokens.** RTK never touches what the model writes.
+- **Your prompt, the system prompt, or conversation history.** These are input tokens RTK has no visibility into.
+- **Commands with no matching filter.** These pass through untouched and are tracked at 0% savings. See `rtk gain --history`.
+
+## See also
+
+- [What RTK Optimizes](what-rtk-covers.md) — per-command bash output reduction
+- [Token Savings Analytics](../analytics/gain.md) — reading the `rtk gain` dashboard
@@ -2,7 +2,7 @@
 title: Telemetry & Privacy
 description: What RTK collects, how to opt out, and your GDPR rights
 sidebar:
-  order: 3
+  order: 4
 ---

 # Telemetry & Privacy
@@ -21,7 +21,7 @@ Without telemetry, we have no visibility into:
 - Which commands are used most and need the best filters
 - Which filters are underperforming and need improvement
 - Which ecosystems to prioritize for new filter development
- How much value RTK delivers to users (token savings in $ terms)
+- How much bash output RTK removes before it reaches the model
 - Whether users stay engaged over time or churn after trying RTK

 This data directly drives our roadmap. For example, if telemetry shows that 40% of users run Python commands but only 10% of our filters cover Python, we know where to invest next.
@@ -65,9 +65,9 @@ This data directly drives our roadmap. For example, if telemetry shows that 40%

 | Field | Example | Purpose |
 |-------|---------|---------|
-| `passthrough_top` | `["git:15", "npm:8"]` | Top 5 commands with 0% savings — these need filters |
+| `passthrough_top` | `["git:15", "npm:8"]` | Top 5 commands with 0% bash output reduction — these need filters |
 | `parse_failures_24h` | `3` | Filter fragility — high count means filters are breaking |
-| `low_savings_commands` | `["rtk docker ps:25%"]` | Commands averaging <30% savings — filters to improve |
+| `low_savings_commands` | `["rtk <cmd>:25%"]` | Commands averaging <30% bash output reduction — filters to improve. The example is a placeholder, not a measured value |
 | `avg_savings_per_command` | `68.5` | Unweighted average (vs global which is volume-biased) |

 ### Ecosystem distribution
@@ -88,7 +88,7 @@ This data directly drives our roadmap. For example, if telemetry shows that 40%
 | Field | Example | Purpose |
 |-------|---------|---------|
 | `tokens_saved_30d` | `12000000` | 30-day token savings for trend analysis |
-| `estimated_savings_usd_30d` | `36.0` | Estimated dollar value saved (at ~$3/Mtok input pricing, Claude Sonnet) |
+| `estimated_savings_usd_30d` | — | A USD value derived from the estimated tokens saved and a fixed internal constant. It is not a measured cost and does not reflect any provider's pricing |

 ### Adoption

@@ -2,7 +2,7 @@
 title: Troubleshooting
 description: Common RTK issues and how to fix them
 sidebar:
-  order: 2
+  order: 3
 ---

 # Troubleshooting
@@ -21,14 +21,14 @@ rtk: 'gain' is not a rtk command. See 'rtk --help'.
 ```bash
 cargo uninstall rtk
 curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
-rtk gain    # should now show token savings stats
+rtk gain    # should now show the savings dashboard
 ```

 ## How to tell which rtk you have

 | If `rtk gain`... | You have |
 |------------------|----------|
-| Shows token savings dashboard | Rust Token Killer ✅ |
+| Shows the savings dashboard | Rust Token Killer ✅ |
 | Returns "not a rtk command" | Rust Type Kit ❌ |

 ## AI assistant not using RTK
@@ -1,6 +1,6 @@
 ---
 title: What RTK Optimizes
-description: Commands and ecosystems automatically optimized by RTK with typical token savings
+description: Commands and ecosystems automatically optimized by RTK, with typical bash output reduction
 sidebar:
  order: 1
 ---
@@ -9,12 +9,16 @@ sidebar:

 Once RTK is installed with a hook, these commands are automatically intercepted and filtered. You run them normally — the hook rewrites them transparently before execution.

-Typical savings: 60-99%.
+Typical bash output reduction: 60-99%.
+
+:::note
+Every percentage below measures **bash output bytes removed** — the only thing RTK controls. Those bytes are one contributor to input tokens, and input tokens are only part of a bill that also counts output tokens. See [How RTK Savings Work](./savings-explained.md) before reading these numbers as cost figures.
+:::

 ## Git

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `git status` | 75-93% | Compact stat format, grouped by state |
 | `git log` | 80-92% | Hash + author + subject only |
 | `git diff` | 70% | Context reduced, headers stripped |
@@ -23,8 +27,8 @@ Typical savings: 60-99%.

 ## GitHub CLI

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `gh pr view` | 87% | Removes ASCII art and verbose metadata |
 | `gh pr checks` | 79% | Status + name only, failures highlighted |
 | `gh run list` | 82% | Compact workflow run summary |
@@ -32,15 +36,15 @@ Typical savings: 60-99%.

 ## Graphite (Stacked PRs)

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `gt log` | 75% | Stack summary only |
 | `gt status` | 70% | Current branch context |

 ## Cargo / Rust

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `cargo test` | 90% | Failures only, passed tests suppressed |
 | `cargo nextest` | 90% | Same as test |
 | `cargo build` | 80% | Errors and warnings only |
@@ -49,8 +53,8 @@ Typical savings: 60-99%.

 ## JavaScript / TypeScript

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `jest` | 94-99% | Failures only |
 | `vitest` | 94-99% | Failures only |
 | `tsc` | 75% | Type errors grouped by file |
@@ -63,8 +67,8 @@ Typical savings: 60-99%.

 ## Python

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `pytest` | 80-90% | Failures only |
 | `ruff check` | 75% | Violations grouped by file |
 | `mypy` | 75% | Type errors grouped by file |
@@ -72,32 +76,32 @@ Typical savings: 60-99%.

 ## Go

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `go test` | 80-90% | Failures only |
 | `golangci-lint run` | 75% | Violations grouped by file |
 | `go build` | 75% | Errors only |

 ## Ruby

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `rspec` | 80-90% | Failures only |
 | `rubocop` | 75% | Offenses grouped by file |
 | `rake` | 70% | Task output, build errors highlighted |

 ## .NET

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `dotnet build` | 80% | Errors and warnings only |
 | `dotnet test` | 85-90% | Failures only |
 | `dotnet format` | 75% | Changed files only |

 ## Docker / Kubernetes

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `docker ps` | 65% | Essential columns (name, image, status, port) |
 | `docker images` | 60% | Name + tag + size only |
 | `docker logs` | 70% | Deduplicated, last N lines |
@@ -107,8 +111,8 @@ Typical savings: 60-99%.

 ## Files and Search

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `ls` | 80% | Tree format with file counts |
 | `find` | 75% | Tree format |
 | `grep` | 70% | Truncated lines, grouped by file |
@@ -119,15 +123,15 @@ Typical savings: 60-99%.

 ## Cloud and Data

-| Command | Savings | What changes |
-|---------|---------|--------------|
+| Command | Bash output reduction | What changes |
+|---------|----------------------|--------------|
 | `aws` | 70% | JSON condensed, relevant fields only |
 | `psql` | 65% | Query results without decoration |
 | `curl` | 60% | Response body only, headers stripped |

 ## Global flags

-These flags apply to all RTK commands and can push savings even higher:
+These flags apply to all RTK commands and can push the bash output reduction even higher:

 | Flag | Description |
 |------|-------------|
@@ -261,9 +261,7 @@ EOF

 ### Token Estimation

-rtk estimates tokens using `text.len() / 4` (4 characters per token average).
-
-**Accuracy**: ±10% compared to actual LLM tokenization (sufficient for trends).
+`rtk gain` estimates tokens as `bytes / 4` (`src/core/tracking.rs:1284`). RTK ships no real tokenizer by design: embedding one would cost startup time and would require a tokenizer per model, or a per-session model lookup, which RTK does not implement. The same estimator is applied to raw and filtered output, so the percentage is reliable; the absolute token counts are approximate and will not match your provider's billing.

 ### Savings Calculation

@@ -274,10 +272,12 @@ Saved Tokens    = Input - Output
 Savings %       = (Saved / Input) × 100
 ```

+`Savings %` is a bash output byte ratio. Those bytes are one contributor to input tokens, and input tokens are only part of a bill that also counts output tokens.
+
 ### Typical Savings by Command

-| Command | Typical Savings | Mechanism |
-|---------|----------------|-----------|
+| Command | Bash output reduction | Mechanism |
+|---------|----------------------|-----------|
 | `rtk git status` | 77-93% | Compact stat format |
 | `rtk eslint` | 84% | Group by rule |
 | `rtk jest` | 94-99% | Show failures only |
@@ -1,9 +1,25 @@
 # RTK - Documentation fonctionnelle complete

-> **rtk (Rust Token Killer)** -- Proxy CLI haute performance qui reduit la consommation de tokens LLM de 60 a 90%.
+> **rtk (Rust Token Killer)** -- Proxy CLI haute performance qui reduit jusqu'a 90% de la sortie bash lue par votre agent.

 Binaire Rust unique, zero dependances externes, overhead < 10ms par commande.

+## A propos des pourcentages d'economies
+
+Tous les pourcentages notes **Economies** dans ce document sont des **reductions d'octets de sortie bash** : la sortie qu'une commande shell renvoie avant que l'agent ne la lise. Ce n'est pas equivalent a une reduction de facture du meme ordre.
+
+```
+Octets de sortie bash  ->  Tokens d'entree  ->  Cout
+   filtres par RTK         une source parmi      tokens d'entree
+                           plusieurs             + tokens de sortie
+```
+
+La sortie bash n'est qu'une source parmi d'autres pour les tokens d'entree, aux cotes de votre prompt, du prompt systeme et de l'historique de conversation. Les tokens d'entree ne representent eux-memes qu'une partie de la facture, qui compte aussi les tokens de sortie. La reduction se dilue a chaque etape.
+
+Les compteurs de tokens affiches par RTK sont estimes a `octets / 4` : RTK n'embarque pas de tokenizer, donc **les pourcentages sont fiables mais les nombres absolus de tokens sont approximatifs**.
+
+Explication complete : [How RTK Savings Work](../guide/resources/savings-explained.md)
+
 ---

 ## Table des matieres
@@ -80,7 +96,7 @@ rtk ls [args...]

 Tous les drapeaux natifs de `ls` sont supportes (`-l`, `-a`, `-h`, `-R`, etc.).

-**Economies :** ~80% de reduction de tokens
+**Economies :** ~80%

 **Avant / Apres :**
 ```
@@ -1400,11 +1416,13 @@ Aucune donnee personnelle, aucun contenu de commande, aucun chemin de fichier n'

 ## Resume des economies par categorie

-| Categorie | Commandes | Economies typiques |
+Reductions d'octets de sortie bash (voir [A propos des pourcentages d'economies](#a-propos-des-pourcentages-deconomies)).
+
+| Categorie | Commandes | Reduction de sortie bash |
 |-----------|-----------|-------------------|
 | **Fichiers** | ls, tree, read, find, grep, diff | 60-80% |
 | **Git** | status, log, diff, show, add, commit, push, pull | 75-92% |
-| **GitHub** | pr, issue, run, api | 26-87% |
+| **GitHub** | pr, issue, run, api | 79-87% |
 | **Tests** | cargo test, vitest, playwright, pytest, go test | 90-99% |
 | **Build/Lint** | cargo build, tsc, eslint, prettier, next, ruff, clippy | 70-87% |
 | **Paquets** | pnpm, npm, pip, deps, prisma | 60-80% |
@@ -1,6 +1,16 @@
 # RTK Tracking API Documentation

-Comprehensive documentation for RTK's token savings tracking system.
+Comprehensive documentation for RTK's tracking system, which records how much **bash output** each filtered command removed.
+
+Everything the tracker stores is measured on bash output bytes, converted to estimated tokens:
+
+```
+Bash output bytes  ->  Input tokens  ->  Cost
+ what RTK filters      one input source     input + output tokens
+                       among several
+```
+
+Bash output is one contributor to input tokens, alongside your prompt, the system prompt and conversation history. Input tokens are in turn only part of the bill, which also counts output tokens. `savings_pct` is therefore a **bash output byte ratio** — not a cost figure and not a share of your token bill.

 ## Table of Contents

@@ -14,9 +24,9 @@ Comprehensive documentation for RTK's token savings tracking system.

 ## Overview

-RTK's tracking system records every command execution to provide analytics on token savings. The system:
+RTK's tracking system records every command execution to provide analytics on bash output reduction. The system:
 - Stores command history in SQLite (~/.local/share/rtk/tracking.db)
- Tracks input/output tokens, savings percentage, and execution time
+- Tracks estimated input/output tokens, bash output reduction percentage, and execution time
 - Automatically cleans up records older than 90 days
 - Provides aggregation APIs (daily/weekly/monthly)
 - Exports to JSON/CSV for external integrations
@@ -75,8 +85,8 @@ impl Tracker {
        &self,
        original_cmd: &str,      // Standard command (e.g., "ls -la")
        rtk_cmd: &str,            // RTK command (e.g., "rtk ls")
-        input_tokens: usize,      // Estimated input tokens
-        output_tokens: usize,     // Actual output tokens
+        input_tokens: usize,      // Estimated tokens from raw output (bytes / 4)
+        output_tokens: usize,     // Estimated tokens after filtering (bytes / 4)
        exec_time_ms: u64,        // Execution time in milliseconds
    ) -> Result<()>;

@@ -106,8 +116,8 @@ pub struct GainSummary {
    pub total_commands: usize,              // Total commands recorded
    pub total_input: usize,                 // Total input tokens
    pub total_output: usize,                // Total output tokens
-    pub total_saved: usize,                 // Total tokens saved
-    pub avg_savings_pct: f64,               // Average savings percentage
+    pub total_saved: usize,                 // Total estimated tokens saved
+    pub avg_savings_pct: f64,               // Average bash output reduction, in percent
    pub total_time_ms: u64,                 // Total execution time (ms)
    pub avg_time_ms: u64,                   // Average execution time (ms)
    pub by_command: Vec<(String, usize, usize, f64, u64)>, // Top 10 commands
@@ -127,7 +137,7 @@ pub struct DayStats {
    pub input_tokens: usize,     // Total input tokens
    pub output_tokens: usize,    // Total output tokens
    pub saved_tokens: usize,     // Total tokens saved
-    pub savings_pct: f64,        // Savings percentage
+    pub savings_pct: f64,        // Bash output reduction, in percent
    pub total_time_ms: u64,      // Total execution time (ms)
    pub avg_time_ms: u64,        // Average execution time (ms)
 }
@@ -178,8 +188,8 @@ Individual command record from history.
 pub struct CommandRecord {
    pub timestamp: DateTime<Utc>, // UTC timestamp
    pub rtk_cmd: String,           // RTK command used
-    pub saved_tokens: usize,       // Tokens saved
-    pub savings_pct: f64,          // Savings percentage
+    pub saved_tokens: usize,       // Estimated tokens saved
+    pub savings_pct: f64,          // Bash output reduction, in percent
 }
 ```

@@ -206,6 +216,8 @@ impl TimedExecution {

 ### Utility Functions

+`rtk gain` estimates tokens as `bytes / 4` (`src/core/tracking.rs:1284`). RTK ships no real tokenizer by design: embedding one would cost startup time and would require a tokenizer per model, or a per-session model lookup, which RTK does not implement. The same estimator is applied to raw and filtered output, so the percentage is reliable; the absolute token counts are approximate and will not match your provider's billing.
+
 ```rust
 /// Estimate token count (~4 chars = 1 token)
 pub fn estimate_tokens(text: &str) -> usize;
@@ -491,10 +503,10 @@ CREATE TABLE commands (
    timestamp TEXT NOT NULL,           -- RFC3339 UTC timestamp
    original_cmd TEXT NOT NULL,        -- Original command (e.g., "ls -la")
    rtk_cmd TEXT NOT NULL,             -- RTK command (e.g., "rtk ls")
-    input_tokens INTEGER NOT NULL,     -- Estimated input tokens
-    output_tokens INTEGER NOT NULL,    -- Actual output tokens
+    input_tokens INTEGER NOT NULL,     -- Estimated tokens from raw output (bytes / 4)
+    output_tokens INTEGER NOT NULL,    -- Estimated tokens after filtering (bytes / 4)
    saved_tokens INTEGER NOT NULL,     -- input_tokens - output_tokens
-    savings_pct REAL NOT NULL,         -- (saved/input) * 100
+    savings_pct REAL NOT NULL,         -- (saved/input) * 100, a bash output byte ratio
    exec_time_ms INTEGER DEFAULT 0     -- Execution time in milliseconds
 );

@@ -12,7 +12,7 @@ Relationship to `src/hooks/`: that component **creates** these files; this direc

 ## Purpose

-LLM agent integrations that intercept CLI commands and route them through RTK for token optimization. Each hook transparently rewrites raw commands (e.g., `git status`) to their RTK equivalents (e.g., `rtk git status`), delivering 60-90% token savings without requiring the agent or user to change their workflow.
+LLM agent integrations that intercept CLI commands and route them through RTK for token optimization. Each hook transparently rewrites raw commands (e.g., `git status`) to their RTK equivalents (e.g., `rtk git status`), cutting up to 90% of the bash output that reaches the LLM context without requiring the agent or user to change their workflow.

 ## How It Works

@@ -24,7 +24,7 @@ Agent runs command (e.g., "cargo test --nocapture")
  -> Registry matches pattern, returns "rtk cargo test --nocapture"
  -> Hook sends response in agent-specific JSON format
  -> Agent executes "rtk cargo test --nocapture" instead
-  -> Filtered output reaches LLM (~90% fewer tokens)
+  -> Filtered output reaches LLM (up to 90% fewer bash output bytes)
 ```

 All rewrite logic lives in the Rust binary (`src/discover/registry.rs`). Hook scripts are **thin delegates** that handle agent-specific JSON formats and call `rtk rewrite` for the actual decision. This ensures a single source of truth for all 70+ rewrite patterns.
@@ -29,4 +29,4 @@ rtk proxy <cmd>       # Run raw (no filtering, for debugging)

 ## Why

-RTK filters and compresses command output before it reaches the LLM context, saving 60-90% tokens on common operations. Always use `rtk <cmd>` instead of raw commands.
+RTK filters and compresses command output before it reaches the LLM context, cutting up to 90% of the bash output on common operations. Always use `rtk <cmd>` instead of raw commands.
@@ -1,6 +1,6 @@
 # RTK - Rust Token Killer

-**Usage**: Token-optimized CLI proxy (60-90% savings on dev operations)
+**Usage**: Token-optimized CLI proxy (cuts up to 90% of bash output)

 ## Meta Commands (always use rtk directly)

@@ -29,4 +29,4 @@ rtk proxy <cmd>       # Run raw (no filtering, for debugging)

 ## Why

-RTK filters and compresses command output before it reaches the LLM context, saving 60-90% tokens on common operations. Always use `rtk <cmd>` instead of raw commands.
+RTK filters and compresses command output before it reaches the LLM context, cutting up to 90% of the bash output on common operations. Always use `rtk <cmd>` instead of raw commands.
@@ -1,6 +1,6 @@
 # RTK — Copilot Integration (VS Code Copilot Chat + Copilot CLI)

-**Usage**: Token-optimized CLI proxy (60-90% savings on dev operations)
+**Usage**: Token-optimized CLI proxy (cuts up to 90% of bash output)

 ## What's automatic

@@ -29,4 +29,4 @@ rtk proxy <cmd>       # Run raw (no filtering, for debugging)

 ## Why

-RTK filters and compresses command output before it reaches the LLM context, saving 60-90% tokens on common operations. Always use `rtk <cmd>` instead of raw commands.
+RTK filters and compresses command output before it reaches the LLM context, cutting up to 90% of the bash output on common operations. Always use `rtk <cmd>` instead of raw commands.
@@ -5,7 +5,7 @@
 ## Design Intent

 RTK's Pi extension is a **rewrite-only token optimizer**. It mutates bash commands to their
-`rtk`-prefixed equivalents, saving 60–90% context tokens.
+`rtk`-prefixed equivalents, cutting up to 90% of the bash output that reaches the context.

 **Permission gating is intentionally out of scope.** RTK does not block, confirm, or audit
 commands — that concern belongs to a dedicated permission extension (e.g. one that gates
@@ -29,4 +29,4 @@ rtk proxy <cmd>       # Run raw (no filtering, for debugging)

 ## Why

-RTK filters and compresses command output before it reaches the LLM context, saving 60-90% tokens on common operations. Always use `rtk <cmd>` instead of raw commands.
+RTK filters and compresses command output before it reaches the LLM context, cutting up to 90% of the bash output on common operations. Always use `rtk <cmd>` instead of raw commands.
@@ -1,6 +1,6 @@
 # RTK Plugin for OpenClaw

-Transparently rewrites shell commands executed via OpenClaw's `exec` tool to their RTK equivalents, achieving 60-90% LLM token savings.
+Transparently rewrites shell commands executed via OpenClaw's `exec` tool to their RTK equivalents, cutting up to 90% of the bash output that reaches the LLM context.

 This is the OpenClaw equivalent of the Claude Code hooks in `hooks/rtk-rewrite.sh`.

@@ -73,7 +73,7 @@ Handled by `rtk rewrite` guards:

 ## Measured savings

-| Command | Token savings |
+| Command | Output reduction |
 |---------|--------------|
 | `git log --stat` | 87% |
 | `ls -la` | 78% |
@@ -2,7 +2,7 @@
 * RTK Rewrite Plugin for OpenClaw
 *
 * Transparently rewrites exec tool commands to RTK equivalents
- * before execution, achieving 60-90% LLM token savings.
+ * before execution, cutting up to 90% of the bash output that reaches the LLM context.
 *
 * All rewrite logic lives in `rtk rewrite` (src/discover/registry.rs).
 * This plugin is a thin delegate — to add or change rules, edit the
@@ -2,7 +2,7 @@
  "id": "rtk-rewrite",
  "name": "RTK Token Optimizer",
  "version": "1.0.0",
-  "description": "Transparently rewrites shell commands to their RTK equivalents for 60-90% LLM token savings",
+  "description": "Transparently rewrites shell commands to their RTK equivalents, cutting up to 90% of the bash output reaching the LLM context",
  "homepage": "https://github.com/rtk-ai/rtk",
  "license": "Apache-2.0",
  "configSchema": {
@@ -1,7 +1,7 @@
 {
  "name": "@rtk-ai/rtk-rewrite",
  "version": "1.0.0",
-  "description": "RTK plugin for OpenClaw — rewrites shell commands for 60-90% LLM token savings",
+  "description": "RTK plugin for OpenClaw — rewrites shell commands, cutting up to 90% of the bash output reaching the LLM context",
  "main": "index.ts",
  "license": "Apache-2.0",
  "repository": {
@@ -4,7 +4,7 @@

 ## Scope

-**Read-only dashboards** over the tracking database. Queries token savings, correlates with external spending data, and surfaces adoption metrics. Never modifies the tracking DB.
+**Read-only dashboards** over the tracking database. Queries the recorded bash output reduction, correlates with external spending data, and surfaces adoption metrics. Never modifies the tracking DB.

 Owns: `rtk gain` (savings dashboard), `rtk cc-economics` (cost reduction), `rtk session` (adoption analysis), and Claude Code usage data parsing.

@@ -13,7 +13,7 @@ Does **not** own: recording token savings (that's `core/tracking` called by `cmd
 Boundary rule: if a new module writes to the DB, it belongs in `core/` or `cmds/`, not here. Tool-specific analytics (like `cc_economics` reading Claude Code data) are fine — the boundary is "read-only presentation", not "tool-agnostic".

 ## Purpose
-Token savings analytics, economic modeling, and adoption metrics.
+Bash output reduction analytics, economic modeling, and adoption metrics. The stored percentages measure output bytes; token counts are `bytes / 4` estimates, not billed tokens.

 These modules read from the SQLite tracking database to produce dashboards, spending estimates, and session-level adoption reports.

@@ -2,7 +2,7 @@

 ## Scope

-**Command execution and output filtering.** Every module here calls an external CLI tool (`Command::new("some_tool")`), transforms its stdout/stderr to reduce token consumption, and records savings via `core/tracking`.
+**Command execution and output filtering.** Every module here calls an external CLI tool (`Command::new("some_tool")`), transforms its stdout/stderr to reduce the bytes the agent reads, and records the reduction via `core/tracking`.

 Owns: all command-specific filter logic, organized by ecosystem (git, rust, js, python, go, dotnet, cloud, system). Cross-ecosystem routing (e.g., `lint_cmd` detecting Python and delegating to `ruff_cmd`) is an intra-component concern.

@@ -299,7 +299,7 @@ Adding a new filter or command requires changes in multiple places. For TOML-vs-
   - Add variant to `Commands` enum in `main.rs` with `#[arg(trailing_var_arg = true, allow_hyphen_values = true)]`
   - Add routing match arm in `main.rs`: `Commands::Mycmd { args } => mycmd_cmd::run(&args, cli.verbose)?,`
 3. **Add rewrite pattern** — Entry in `src/discover/rules.rs` (PATTERNS + RULES arrays at matching index) so hooks auto-rewrite the command
-4. **Write tests** — Real fixture, snapshot test, token savings >= 60% (see [testing rules](../../.claude/rules/cli-testing.md))
+4. **Write tests** — Real fixture, snapshot test, >= 60% reduction in bash output (measured with RTK's token estimator, see [testing rules](../../.claude/rules/cli-testing.md))
 5. **Update docs** — Ecosystem README (CHANGELOG.md is auto-generated by release-please)

 ### TOML filter (simple line-based filtering)
@@ -31,7 +31,7 @@ Key behaviours:
 - **Reactor Summary preservation** — for multi-module builds, the trailing `Reactor Summary for <root>` block with per-module SUCCESS/FAILURE rows is kept (toggled by a `[INFO] Reactor Summary for ` header and cleared on `BUILD SUCCESS` / `BUILD FAILURE`).
 - **Failure cap** — both the count of emitted failing test classes and the size of the `[ERROR] Failures:` summary block are bounded by `MAX_MVN_FAILING_CLASSES = CAP_WARNINGS` (the shared test-failure cap class from `src/core/truncate.rs`, same binding as pytest/rspec/rake/runner). Excess emissions are replaced by a single `… +N more failing test classes` / `… +N more failures` tail (canonical `join_with_overflow` shape) to keep large failure sets compact; the raw output stays recoverable via the tee `[full output: …]` hint. Per the core cap policy, a cap of `0` means summary-only: no blocks emitted, the tail still counts every dropped class.

-Token-savings tests run inline as part of `cargo test --all` and verify ≥90% savings for `mvn test` and ≥85% for `mvn install` on full synthetic fixtures (gzipped, ~1100 lines each). The `flate2` dependency (already in `Cargo.toml`) decompresses the ~3 KB gzipped fixtures in milliseconds.
+Savings tests run inline as part of `cargo test --all` and verify a ≥90% reduction in bash output for `mvn test` and ≥85% for `mvn install` on full synthetic fixtures (gzipped, ~1100 lines each), measured with the local `count_tokens` estimator rather than a real tokenizer. The `flate2` dependency (already in `Cargo.toml`) decompresses the ~3 KB gzipped fixtures in milliseconds.

 ### Integrity-check whitelist

@@ -4,6 +4,8 @@

 ## Specifics

+Percentages below are reductions in bash output, measured with RTK's token estimator rather than a real tokenizer.
+
 - `rake_cmd.rs` filters Minitest output via `rake test` / `rails test`; state machine text parser, failures only (85-90% reduction)
 - `rspec_cmd.rs` uses JSON injection (`--format json`) with text fallback; failures only (60%+ reduction)
 - `rubocop_cmd.rs` uses JSON injection, groups by cop/severity (60%+ reduction)
@@ -40,10 +40,10 @@ CREATE TABLE commands (
  original_cmd TEXT,           -- "ls -la"
  rtk_cmd TEXT,                -- "rtk ls"
  project_path TEXT,           -- cwd (for project-scoped stats)
-  input_tokens INTEGER,        -- estimated from raw output
-  output_tokens INTEGER,       -- estimated from filtered output
+  input_tokens INTEGER,        -- estimated from raw output (bytes / 4, no tokenizer)
+  output_tokens INTEGER,       -- estimated from filtered output (bytes / 4)
  saved_tokens INTEGER,        -- input - output
-  savings_pct REAL,            -- (saved / input) * 100
+  savings_pct REAL,            -- (saved / input) * 100, i.e. reduction in bash output bytes
  exec_time_ms INTEGER         -- elapsed milliseconds
 );

@@ -46,7 +46,7 @@ When a hook sends `cargo fmt --all && cargo test 2>&1 | tail -20`:
 1. Extracts commands from the JSONL (via `SessionProvider` trait — currently only Claude Code)
 2. Splits compound commands using the same lexer-based tokenization
 3. Classifies each command against the same rules used for live rewriting
-4. Aggregates results: which commands could have been rewritten, estimated token savings, adoption rate
+4. Aggregates results: which commands could have been rewritten, estimated bash output reduction (an estimate of shell output, not billed tokens), adoption rate

 The classification logic is shared between discover and rewrite — same patterns, same rules, different consumers.

@@ -9,7 +9,7 @@ Files are concatenated alphabetically by `build.rs` into a single TOML blob embe

 TOML filters strip noise lines — they don't reformat output. The filtered result must still look like real command output (see [Design Philosophy](../../CONTRIBUTING.md#design-philosophy)). For the full TOML-vs-Rust decision criteria, see [CONTRIBUTING.md](../../CONTRIBUTING.md#toml-vs-rust-which-one).

-TOML works well for commands with **predictable, line-by-line text output** where regex filtering achieves 60%+ savings:
+TOML works well for commands with **predictable, line-by-line text output** where regex filtering cuts 60%+ of the output bytes:
 - Install/update logs (brew, composer, poetry) — strip `Using ...` / `Already installed` lines
 - System monitoring (df, ps, systemctl) — keep essential rows, drop headers/decorations
 - Simple linters (shellcheck, yamllint, hadolint) — strip context, keep findings
@@ -82,7 +82,7 @@ For build tools (next, webpack, vite, cargo, etc.)
 ### Ultra (verbosity=2+)
 - Symbols: ✓✗⚠ pkg: ^
 - Ultra-compressed
- 30-50% token reduction
+- Replaces labels and status words with single-character symbols, dropping whatever Compact still spells out

 ## Error Handling