docs(framework): conform token-optimization recipe to recipe contract

Align the recipe with references/recipe-contract.md: drop the Time row
(no longer in the template), name the section "Steps to <outcome>" instead
of a bare Steps, remove the "ranked by impact" filler line, and give each
step how-bullets plus a concrete example.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: alexsoyes

recipes/token-optimization.md

@@ -2,117 +2,124 @@
 
 > **Goal:** Cut token usage and cost in AI coding assistants without losing output quality.
 
-|                   |                                                                              |
-| ----------------- | ---------------------------------------------------------------------------- |
-| **Level**         | Intermediate                                                                 |
-| **Time**          | ~15 min                                                                      |
+|                   |                                                                                    |
+| ----------------- | ---------------------------------------------------------------------------------- |
+| **Level**         | Intermediate                                                                       |
 | **Prerequisites** | An AI coding assistant (Claude Code, GitHub Copilot, Codex, Cursor, …); a terminal |
 
 ## Why
 
-Tokens are the bill. Every turn re-sends your context window — instructions, file reads, command output, the model's own narration — and you pay for all of it, every time. Most of it is waste: filler prose, noisy logs, stale context, oversized instruction files. The tips below attack each source. Stack them and large savings are realistic; every percentage here is **as reported by the tool**, not an independent benchmark.
+**Token usage** is the bill. Every turn re-sends your whole **context window** — instructions, file reads, command output, narration — and you pay for it again. Most of it is waste: filler prose, noisy logs, stale context, bloated instruction files. Reach for this recipe when **cost** climbs faster than output.
 
-> **Measure before you optimise.** You cannot cut what you do not see.
+## Steps to cut token usage
 
-## Best tips
+### 🟢 Beginner
 
-Ranked by impact-to-effort. Start at the top.
+#### 1) 📊 Measure first
 
-#### 1) Measure first
+You cannot cut what you cannot see, so find what fills the window before changing anything.
 
-You cannot improve what you do not track, and the bill is rarely where you think — cache reads usually dominate, not generation.
-
-- In Claude Code: `/context` shows what fills the window, `/cost` shows the session cost and plan usage, `/insights` reports your session patterns and friction points.
-- For a per-prompt breakdown across every session, use [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code).
+- Built-in: run `/context`, `/cost`, and `/insights` in Claude Code.
+- Cross-session detail: install [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and run it with `uvx`.
 
 ```bash
 $ uvx --from prompt-analytics-for-claude-code prompt-analytics summary
-# per-prompt tokens & cost from your local logs — cache reads dominate the total
+# per-prompt tokens & cost from local logs — cache reads usually dominate
 ```
 
-#### 2) Trim your instruction file
+#### 2) ✂️ Trim your instruction file
 
-`CLAUDE.md` (or `.github/copilot-instructions.md`) ships in **every** turn, so each wasted line is taxed on every message.
+Your instruction file ships every turn, so each cut line saves on every message.
 
-- Keep it short; add explicit conciseness rules.
-- Drop-in ruleset: [`drona23/claude-token-efficient`](https://github.com/drona23/claude-token-efficient) (savings vary by model; measure your own).
+- It lives at `CLAUDE.md` (or `.github/copilot-instructions.md`).
+- Cut it to essentials and add explicit conciseness rules.
+- Reuse the [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) ruleset.
 
 ```md
 # CLAUDE.md
 - Terse answers. No preamble, no "Let me…", no closing summary.
 - Keep verbatim: code, quoted errors, security warnings. Cut the rest.
 ```
 
-#### 3) Make the agent talk less
+#### 3) 🗜️ Compact deliberately
+
+Compacting on your terms keeps what matters instead of letting auto-compaction guess.
+
+- Watch context use and act around 60–70%.
+- Run `/compact` with focus instructions naming what to keep.
+
+```bash
+$ /compact keep the repro steps and the failing test; drop the file dumps
+```
+
+### 🟡 Intermediate
+
+#### 4) 🗣️ Make the agent talk less
 
-Output is repetition — "Let me explain…", "Here's a summary…". You pay to generate every word.
+Output is repetition you pay to generate, so cap the chatter.
 
-- The [`caveman`](https://github.com/JuliusBrussee/caveman) skill forces short, filler-free replies (reported ~65% output-token cut, code and data intact). Auto-detects 30+ agents.
+- Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill (auto-detects 30+ agents).
+- It forces short, filler-free replies (reported ~65% output cut, code intact).
 
 ```text
-before: "Great question! Let me walk you through each of the steps involved…"
+before: "Great question! Let me walk you through each step involved…"
 after:  "3 steps:"
 ```
 
-#### 4) Filter noisy command output
+#### 5) 🧹 Filter noisy command output
 
-Test runs, installs, and build logs flood the context with lines the model never needs.
+Test, install, and build logs flood context with lines the model never needs.
 
-- A CLI proxy strips them before they land: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). Both report 60–90% on noisy output, zero overhead when no filter matches.
+- Install a CLI proxy: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters).
+- Run noisy commands through it; it keeps only the signal (reported 60–90%).
 
 ```bash
 $ rtk proxy npm test
 # full build log in → only failures + final summary kept
 ```
 
-#### 5) Prefer CLI over MCP
+#### 6) 🔌 Prefer CLI over MCP
 
-An MCP server loads its full tool schema into **every** turn; a CLI call costs a few tokens only when you use it.
+An MCP server loads its full schema every turn, while a CLI costs tokens only when called.
 
-- Reach for the CLI when one exists; keep MCP for what truly needs it. See [`mcp-installation.md`](mcp-installation.md).
+- Use the CLI when one exists (`gh`, `acli`, …); keep MCP for what has none.
+- See [`mcp-installation.md`](mcp-installation.md).
 
 ```bash
-$ gh pr list        # a few tokens per call
-# vs a GitHub MCP server: its whole schema rides along every turn
+$ gh pr list   # a few tokens per call, vs a GitHub MCP schema riding along every turn
 ```
 
-#### 6) Use progressive disclosure
+### 🔴 Expert
 
-Don't paste big procedural docs into context. Load knowledge only when the task needs it.
+#### 7) 📚 Use progressive disclosure
 
-- Install an AIDD framework so skills, rules, and runbooks load on demand instead of riding along every turn.
+Load knowledge only when the task needs it, instead of riding along every turn.
+
+- Install an AIDD framework so skills, rules, and runbooks load on demand.
 
 ```text
 skill description matched → its steps load
 no match → 0 tokens spent
 ```
 
-#### 7) Compact deliberately
-
-Auto-compaction fires late and may drop what you wanted kept.
-
-- Run `/compact` around 60–70% context, passing focus instructions for what to retain.
-
-```bash
-$ /compact keep the repro steps and the failing test; drop the file dumps
-```
-
-#### 8) Route by difficulty
+#### 8) 🎯 Route by difficulty
 
-The top model on a routine task is wasted spend.
+The top model on routine work is wasted spend.
 
-- Send research and routine work to a cheaper/faster model or a fresh subagent context; reserve the strongest model for the hard reasoning.
+- Send research and boilerplate to a cheaper model or a fresh subagent.
+- Reserve the strongest model for hard reasoning.
 
 ```text
 research / boilerplate → small model or subagent
 architecture / tricky bug → top model
 ```
 
-#### 9) Cap extended thinking
+#### 9) ✅ Cap extended thinking
 
-Extended reasoning can silently add thousands of tokens per turn on tasks that don't need it.
+Extended reasoning can silently add thousands of tokens on tasks that don't need it.
 
-- Control it with `MAX_THINKING_TOKENS` in your settings — set `0` to turn extended thinking off when you don't need it. See the [Claude Code settings docs](https://code.claude.com/docs/en/settings).
+- Set `MAX_THINKING_TOKENS` to `0` for routine work.
+- See the [Claude Code settings docs](https://code.claude.com/docs/en/settings).
 
 ```bash
 # settings.json (env)
@@ -121,9 +128,9 @@ Extended reasoning can silently add thousands of tokens per turn on tasks that d
 
 ## Verify
 
-- Run `/cost` (or `prompt-analytics summary`) before and after a typical task — the token count should drop measurably.
+- Run `/cost` before and after a typical task — the token count drops measurably.
 - `/context` shows your instruction file and tool schemas taking a smaller share of the window.
-- A noisy command (test suite, `npm install`) routed through RTK or SNIP returns far fewer lines than the raw run.
+- A noisy command routed through RTK or SNIP returns far fewer lines than the raw run.
 
 ## Related