diff --git a/README.md b/README.md
index a00bafb23..7757d599a 100644
--- a/README.md
+++ b/README.md
@@ -1,93 +1,54 @@
-
+
+ Docs ·
+ Install ·
+ Proof ·
+ Agents ·
+ Discord
+
---
-Every tool call, log line, DB read, RAG chunk, and file your agent injects into a prompt is mostly boilerplate. Headroom strips the noise and keeps the signal — **losslessly, locally, and without touching accuracy.**
+> Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens.
-> **100 logs. One FATAL error buried at position 67. Both runs found it.**
-> Baseline **10,144 tokens** → Headroom **1,260 tokens** — **87% fewer, identical answer.**
-> `python examples/needle_in_haystack_test.py`
+
+ 
+
Live: 10,144 → 1,260 tokens — same FATAL found.
+
----
+## What it does
-## Quick start
+- **Library** — `compress(messages)` in Python or TypeScript, inline in any app
+- **Proxy** — `headroom proxy --port 8787`, zero code changes, any language
+- **Agent wrap** — `headroom wrap claude|codex|cursor|aider|copilot` in one command
+- **MCP server** — `headroom_compress`, `headroom_retrieve`, `headroom_stats` for any MCP client
+- **Cross-agent memory** — shared store across Claude, Codex, Gemini, auto-dedup
+- **`headroom learn`** — mines failed sessions, writes corrections to `CLAUDE.md` / `AGENTS.md`
+- **Reversible (CCR)** — originals never deleted; LLM retrieves on demand
-Works with Anthropic, OpenAI, Google, Bedrock, Vertex, Azure, OpenRouter, and 100+ models via LiteLLM.
-
-**Wrap your coding agent — one command:**
-
-```bash
-pip install "headroom-ai[all]"
-
-headroom wrap claude # Claude Code
-headroom wrap codex # Codex
-headroom wrap cursor # Cursor
-headroom wrap aider # Aider
-headroom wrap copilot # GitHub Copilot CLI
-```
-
-Using `pipx`? Current release wheels are built for Python 3.10 through 3.13, so
-choose a supported interpreter explicitly:
-
-```bash
-pipx install --python python3.13 "headroom-ai[all]"
-```
-
-**Drop it into your own code — Python or TypeScript:**
-
-```python
-from headroom import compress
-
-result = compress(messages, model="claude-sonnet-4-5")
-response = client.messages.create(model="claude-sonnet-4-5", messages=result.messages)
-print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
-```
-
-```typescript
-import { compress } from 'headroom-ai';
-const result = await compress(messages, { model: 'gpt-4o' });
-```
-
-**Or run it as a proxy — zero code changes, any language:**
-
-```bash
-headroom proxy --port 8787
-ANTHROPIC_BASE_URL=http://localhost:8787 your-app
-OPENAI_BASE_URL=http://localhost:8787/v1 your-app
-```
-
----
-
-## Why Headroom
-
-- **Accuracy-preserving.** GSM8K **0.870 → 0.870** (±0.000). TruthfulQA **+0.030**. SQuAD v2 and BFCL both **97%** accuracy after compression. Validated on public OSS benchmarks you can rerun yourself.
-- **Runs on your machine.** No cloud API, no data egress. Compression latency is milliseconds — faster end-to-end for Sonnet / Opus / GPT-4 class models than a hosted service round-trip.
-- **[Kompress-base](https://huggingface.co/chopratejas/kompress-base) on HuggingFace.** Our open-source text compressor, fine-tuned on real agentic traces — tool outputs, logs, RAG chunks, code. Install with `pip install "headroom-ai[ml]"`.
-- **Cross-agent memory and learning.** Claude Code saves a fact, Codex reads it back. `headroom learn` mines failed sessions and writes corrections straight to `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` — reliability compounds over time.
-- **Reversible (CCR).** Compression is not deletion. The model can always call `headroom_retrieve` to pull the original bytes. Nothing is thrown away.
-
-Bundles managed [RTK](https://github.com/rtk-ai/rtk) and [lean-ctx](https://github.com/yvgude/lean-ctx) binaries for local CLI context filtering — full [attribution below](#compared-to).
-
----
-
-## How it fits
+## How it works (30 seconds)
```
Your agent / app
@@ -109,28 +70,30 @@ Bundles managed [RTK](https://github.com/rtk-ai/rtk) and [lean-ctx](https://gith
LLM provider (Anthropic · OpenAI · Bedrock · …)
```
+- **ContentRouter** — detects content type, selects the right compressor
+- **SmartCrusher / CodeCompressor / Kompress-base** — compress JSON, AST, or prose
+- **CacheAligner** — stabilizes prefixes so provider KV caches actually hit
+- **CCR** — stores originals locally; LLM calls `headroom_retrieve` if it needs them
+
→ [Architecture](https://headroom-docs.vercel.app/docs/architecture) · [CCR reversible compression](https://headroom-docs.vercel.app/docs/ccr) · [Kompress-base model card](https://huggingface.co/chopratejas/kompress-base)
-### Canonical pipeline lifecycle
+## Get started (60 seconds)
-Headroom now exposes one stable request lifecycle across `compress()`, the SDK, and the proxy:
+```bash
+# 1 — Install
+pip install "headroom-ai[all]" # Python
+npm install headroom-ai # Node / TypeScript
-`Setup` → `Pre-Start` → `Post-Start` → `Input Received` → `Input Cached` → `Input Routed` → `Input Compressed` → `Input Remembered` → `Pre-Send` → `Post-Send` → `Response Received`
+# 2 — Pick your mode
+headroom wrap claude # wrap a coding agent
+headroom proxy --port 8787 # drop-in proxy, zero code changes
+# or: from headroom import compress # inline library
-- **Transforms** still do the work: CacheAligner, ContentRouter, SmartCrusher, CodeCompressor, Kompress-base, IntelligentContext / RollingWindow.
-- **Pipeline extensions** observe or customize those lifecycle stages via `on_pipeline_event(...)`.
-- **Compression hooks** still work and now sit alongside the canonical lifecycle instead of being the only extension seam.
-- **Proxy extensions** remain the server/app integration seam for ASGI middleware, routes, and startup policy.
+# 3 — See the savings
+headroom stats
+```
-### Provider slices
-
-Provider and tool-specific behavior is being moved behind dedicated modules under `headroom/providers/` so core orchestration stays focused on lifecycle, sequencing, and policy.
-
-- **CLI/tool slices**: `headroom/providers/claude`, `copilot`, `codex`, `openclaw`
-- **Provider runtime slices**: `headroom/providers/claude`, `gemini`, plus shared backend/runtime dispatch in `headroom/providers/registry.py`
-- **Core files stay orchestration-first**: `wrap.py`, `client.py`, `cli/proxy.py`, and `proxy/server.py` now delegate provider-specific env shaping, API target normalization, backend selection, and transport dispatch instead of inlining those rules.
-
----
+Granular extras: `[proxy]`, `[mcp]`, `[ml]`, `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.
## Proof
@@ -145,69 +108,62 @@ Provider and tool-specific behavior is being moved behind dedicated modules unde
**Accuracy preserved on standard benchmarks:**
-| Benchmark | Category | N | Baseline | Headroom | Delta |
-|------------|----------|----:|---------:|---------:|----------:|
-| GSM8K | Math | 100 | 0.870 | 0.870 | **±0.000**|
-| TruthfulQA | Factual | 100 | 0.530 | 0.560 | **+0.030**|
+| Benchmark | Category | N | Baseline | Headroom | Delta |
+|------------|----------|----:|---------:|---------:|------------|
+| GSM8K | Math | 100 | 0.870 | 0.870 | **±0.000** |
+| TruthfulQA | Factual | 100 | 0.530 | 0.560 | **+0.030** |
| SQuAD v2 | QA | 100 | — | **97%** | 19% compression |
| BFCL | Tools | 100 | — | **97%** | 32% compression |
-Reproduce:
+Reproduce: `python -m headroom.evals suite --tier 1` · [Full benchmarks & methodology](https://headroom-docs.vercel.app/docs/benchmarks)
-```bash
-python -m headroom.evals suite --tier 1
-```
-
-**Community, live:**
-
-
+
60B+ tokens saved by the community — live leaderboard →
+
-→ [Full benchmarks & methodology](https://headroom-docs.vercel.app/docs/benchmarks)
+## Agent compatibility matrix
----
+| Agent | `headroom wrap` | Notes |
+|-------------|:---------------:|----------------------------------|
+| Claude Code | ● | `--memory` · `--code-graph` |
+| Codex | ● | shares memory with Claude |
+| Cursor | ● | prints config — paste once |
+| Aider | ● | starts proxy + launches |
+| Copilot CLI | ● | starts proxy + launches |
+| OpenClaw | ● | installs as ContextEngine plugin |
-## Built for coding agents
+Any OpenAI-compatible client works via `headroom proxy`. MCP-native: `headroom mcp install`.
-| Agent | One-command wrap | Notes |
-|--------------------|------------------------------------|------------------------------------------------------------------|
-| **Claude Code** | `headroom wrap claude` | `--memory` for cross-agent memory, `--code-graph` for codebase intel |
-| **Codex** | `headroom wrap codex --memory` | Shares the same memory store as Claude |
-| **Cursor** | `headroom wrap cursor` | Prints Cursor config — paste once, done |
-| **Aider** | `headroom wrap aider` | Starts proxy, launches Aider |
-| **Copilot CLI** | `headroom wrap copilot` | Starts proxy, launches Copilot |
-| **OpenClaw** | `headroom wrap openclaw` | Installs Headroom as ContextEngine plugin |
+## When to use · When to skip
-MCP-native too — `headroom mcp install` exposes `headroom_compress`, `headroom_retrieve`, and `headroom_stats` to any MCP client.
+**Great fit if you…**
+- run AI coding agents daily and want savings without changing your code
+- work across multiple agents and want shared memory
+- need reversible compression — originals always retrievable via CCR
-
-
-
-Drop Headroom into any stack
+Integrations — drop Headroom into any stack
-| Your setup | Hook in with |
-|-------------------------|------------------------------------------------------------------|
-| Any Python app | `compress(messages, model=…)` |
-| Any TypeScript app | `await compress(messages, { model })` |
-| Anthropic / OpenAI SDK | `withHeadroom(new Anthropic())` · `withHeadroom(new OpenAI())` |
-| Vercel AI SDK | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |
-| LiteLLM | `litellm.callbacks = [HeadroomCallback()]` |
-| LangChain | `HeadroomChatModel(your_llm)` |
-| Agno | `HeadroomAgnoModel(your_model)` |
-| Strands | [Strands guide](https://headroom-docs.vercel.app/docs/strands) |
-| ASGI apps | `app.add_middleware(CompressionMiddleware)` |
-| Multi-agent | `SharedContext().put / .get` |
-| MCP clients | `headroom mcp install` |
+| Your setup | Hook in with |
+|------------------------|------------------------------------------------------------------|
+| Any Python app | `compress(messages, model=…)` |
+| Any TypeScript app | `await compress(messages, { model })` |
+| Anthropic / OpenAI SDK | `withHeadroom(new Anthropic())` · `withHeadroom(new OpenAI())` |
+| Vercel AI SDK | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |
+| LiteLLM | `litellm.callbacks = [HeadroomCallback()]` |
+| LangChain | `HeadroomChatModel(your_llm)` |
+| Agno | `HeadroomAgnoModel(your_model)` |
+| Strands | [Strands guide](https://headroom-docs.vercel.app/docs/strands) |
+| ASGI apps | `app.add_middleware(CompressionMiddleware)` |
+| Multi-agent | `SharedContext().put / .get` |
+| MCP clients | `headroom mcp install` |
@@ -227,50 +183,76 @@ MCP-native too — `headroom mcp install` exposes `headroom_compress`, `headroom
----
+
+Pipeline internals
+
+Headroom exposes one stable request lifecycle across `compress()`, the SDK, and the proxy:
+
+`Setup` → `Pre-Start` → `Post-Start` → `Input Received` → `Input Cached` → `Input Routed` → `Input Compressed` → `Input Remembered` → `Pre-Send` → `Post-Send` → `Response Received`
+
+- **Transforms** do the work: CacheAligner, ContentRouter, SmartCrusher, CodeCompressor, Kompress-base, IntelligentContext / RollingWindow.
+- **Pipeline extensions** observe or customize lifecycle stages via `on_pipeline_event(...)`.
+- **Compression hooks** sit alongside the canonical lifecycle as an additional extension seam.
+- **Proxy extensions** remain the server/app integration seam for ASGI middleware, routes, and startup policy.
+
+Provider and tool-specific behavior lives under `headroom/providers/` so core orchestration stays focused on lifecycle, sequencing, and policy.
+
+- **CLI/tool slices**: `headroom/providers/claude`, `copilot`, `codex`, `openclaw`
+- **Provider runtime slices**: `headroom/providers/claude`, `gemini`, plus shared backend/runtime dispatch in `headroom/providers/registry.py`
+- **Core files stay orchestration-first**: `wrap.py`, `client.py`, `cli/proxy.py`, and `proxy/server.py` delegate provider-specific env shaping, API target normalization, backend selection, and transport dispatch.
+
+
## Install
```bash
pip install "headroom-ai[all]" # Python, everything
-npm install headroom-ai # TypeScript / Node
+npm install headroom-ai # TypeScript / Node
docker pull ghcr.io/chopratejas/headroom:latest
```
Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-base), `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.
+Using `pipx`? Choose a supported interpreter explicitly:
+
+```bash
+pipx install --python python3.13 "headroom-ai[all]"
+```
+
→ [Installation guide](https://headroom-docs.vercel.app/docs/installation) — Docker tags, persistent service, PowerShell, devcontainers.
----
+## headroom learn
+
+
+
+
+
+`headroom learn` — mines failed sessions, writes corrections to `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`.
## Documentation
-| Start here | Go deeper |
-|-------------------------------------------------------------------------|------------------------------------------------------------------------|
-| [Quickstart](https://headroom-docs.vercel.app/docs/quickstart) | [Architecture](https://headroom-docs.vercel.app/docs/architecture) |
-| [Proxy](https://headroom-docs.vercel.app/docs/proxy) | [How compression works](https://headroom-docs.vercel.app/docs/how-compression-works) |
-| [MCP tools](https://headroom-docs.vercel.app/docs/mcp) | [CCR — reversible compression](https://headroom-docs.vercel.app/docs/ccr) |
-| [Memory](https://headroom-docs.vercel.app/docs/memory) | [Cache optimization](https://headroom-docs.vercel.app/docs/cache-optimization) |
-| [Failure learning](https://headroom-docs.vercel.app/docs/failure-learning) | [Benchmarks](https://headroom-docs.vercel.app/docs/benchmarks) |
-| [Configuration](https://headroom-docs.vercel.app/docs/configuration) | [Limitations](https://headroom-docs.vercel.app/docs/limitations) |
-
----
+| Start here | Go deeper |
+|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
+| [Quickstart](https://headroom-docs.vercel.app/docs/quickstart) | [Architecture](https://headroom-docs.vercel.app/docs/architecture) |
+| [Proxy](https://headroom-docs.vercel.app/docs/proxy) | [How compression works](https://headroom-docs.vercel.app/docs/how-compression-works) |
+| [MCP tools](https://headroom-docs.vercel.app/docs/mcp) | [CCR — reversible compression](https://headroom-docs.vercel.app/docs/ccr) |
+| [Memory](https://headroom-docs.vercel.app/docs/memory) | [Cache optimization](https://headroom-docs.vercel.app/docs/cache-optimization) |
+| [Failure learning](https://headroom-docs.vercel.app/docs/failure-learning) | [Benchmarks](https://headroom-docs.vercel.app/docs/benchmarks) |
+| [Configuration](https://headroom-docs.vercel.app/docs/configuration) | [Limitations](https://headroom-docs.vercel.app/docs/limitations) |
## Compared to
-Headroom runs **locally**, covers **every** content type (not just CLI or text), works with every major framework, and is **reversible**.
+Headroom runs **locally**, covers **every** content type, works with every major framework, and is **reversible**.
-| | Scope | Deploy | Local | Reversible |
-|----------------------------------|-------------------------------------------------|-------------------------------------|:-----:|:----------:|
-| **Headroom** | All context — tools, RAG, logs, files, history | Proxy · library · middleware · MCP | Yes | Yes |
-| [RTK](https://github.com/rtk-ai/rtk) | CLI command outputs | CLI wrapper | Yes | No |
-| [lean-ctx](https://github.com/yvgude/lean-ctx) | CLI commands, MCP tools, editor rules | CLI wrapper · MCP | Yes | No |
-| [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | Text sent to their API | Hosted API call | No | No |
-| OpenAI Compaction | Conversation history | Provider-native | No | No |
+| | Scope | Deploy | Local | Reversible |
+|------------------------------------------------------------------------------|------------------------------------------------|------------------------------------|:-----:|:----------:|
+| **Headroom** | All context — tools, RAG, logs, files, history | Proxy · library · middleware · MCP | Yes | Yes |
+| [RTK](https://github.com/rtk-ai/rtk) | CLI command outputs | CLI wrapper | Yes | No |
+| [lean-ctx](https://github.com/yvgude/lean-ctx) | CLI commands, MCP tools, editor rules | CLI wrapper · MCP | Yes | No |
+| [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | Text sent to their API | Hosted API call | No | No |
+| OpenAI Compaction | Conversation history | Provider-native | No | No |
-> **Attribution.** Headroom ships with the excellent [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — `git show` → `git show --short`, noisy `ls` → scoped, chatty installers → summarized. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it. Headroom can also use [lean-ctx](https://github.com/yvgude/lean-ctx) as the selected CLI context tool; set `HEADROOM_CONTEXT_TOOL=lean-ctx` before running `headroom wrap ...`.
-
----
+> **Attribution.** Headroom ships with the excellent [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — `git show --short`, scoped `ls`, summarized installers. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it. Headroom can also use [lean-ctx](https://github.com/yvgude/lean-ctx) as the selected CLI context tool; set `HEADROOM_CONTEXT_TOOL=lean-ctx` before running `headroom wrap ...`.
## Contributing
@@ -281,8 +263,6 @@ pip install -e ".[dev]" && pytest
Devcontainers in `.devcontainer/` (default + `memory-stack` with Qdrant & Neo4j). See [CONTRIBUTING.md](CONTRIBUTING.md).
----
-
## Community
- **[Live leaderboard](https://headroomlabs.ai/dashboard)** — 60B+ tokens saved and counting.
diff --git a/docs/superpowers/specs/2026-05-11-readme-redesign-design.md b/docs/superpowers/specs/2026-05-11-readme-redesign-design.md
deleted file mode 100644
index 38cef3928..000000000
--- a/docs/superpowers/specs/2026-05-11-readme-redesign-design.md
+++ /dev/null
@@ -1,258 +0,0 @@
-# README Redesign — Design Spec
-
-**Date:** 2026-05-11
-**Status:** Approved
-**Reference:** [lean-ctx README](https://github.com/yvgude/lean-ctx) — structural and visual inspiration
-
----
-
-## Goal
-
-Redesign `README.md` to match the crispness and scannability of lean-ctx's README while
-foregrounding what makes Headroom distinct: library + proxy + MCP (not CLI-only), reversible
-compression (CCR), and cross-agent memory.
-
----
-
-## Structure (ordered)
-
-### 1. ASCII block logo
-
-Six-row block-letter HEADROOM (same double-width box-drawing style as lean-ctx):
-
-```
- ██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗
- ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║
- ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║
- ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║
- ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║
- ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝
- The context compression layer for AI agents
-```
-
-Tagline on line 7, centered, plain text (no ``).
-
-### 2. Power-stats line (centered `
`)
-
-```
-60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible
-```
-
-### 3. Badge row (centered `
`)
-
-Keep current badges in current order:
-CI · codecov · PyPI · npm · Kompress-base model · Tokens saved · License · Docs
-
-### 4. Nav links (centered `
`)
-
-```
-Docs · Install · Proof · Agents · Discord
-```
-
-Anchor-linked to section IDs in the document:
-- **Docs** → `#documentation`
-- **Install** → `#get-started-60-seconds`
-- **Proof** → `#proof`
-- **Agents** → `#agent-compatibility-matrix`
-- **Discord** → external Discord URL
-
----
-
-### 5. Horizontal rule + blockquote elevator pitch
-
-```
-> Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks,
-> files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens.
-```
-
-Immediately followed by the existing `HeadroomDemo-Fast.gif`, centered using raw HTML:
-
-```html
-
-
-
Live: 10,144 → 1,260 tokens — same FATAL found.
-
-```
-
----
-
-### 6. What it does
-
-Seven bullets, one clause each. No prose paragraphs.
-
-- **Library** — `compress(messages)` in Python or TypeScript, inline in any app
-- **Proxy** — `headroom proxy --port 8787`, zero code changes, any language
-- **Agent wrap** — `headroom wrap claude|codex|cursor|aider|copilot` in one command
-- **MCP server** — `headroom_compress`, `headroom_retrieve`, `headroom_stats` for any MCP client
-- **Cross-agent memory** — shared store across Claude, Codex, Gemini, auto-dedup
-- **`headroom learn`** — mines failed sessions, writes corrections to `CLAUDE.md` / `AGENTS.md`
-- **Reversible (CCR)** — originals never deleted; LLM retrieves on demand
-
----
-
-### 7. How it works (30 seconds)
-
-Keep the existing ASCII pipeline diagram verbatim. Replace all prose beneath it with exactly
-four tight bullets (no more than one clause each), mirroring lean-ctx's pattern:
-
-- **ContentRouter** — detects content type, selects the right compressor
-- **SmartCrusher / CodeCompressor / Kompress-base** — compress JSON, AST, or prose
-- **CacheAligner** — stabilizes prefixes so provider KV caches actually hit
-- **CCR** — stores originals locally; LLM calls `headroom_retrieve` if it needs them
-
-Drop the "Canonical pipeline lifecycle" paragraphs and "Provider slices" paragraphs from main
-body — they move to `` (see Section 12).
-
----
-
-### 8. Get started (60 seconds)
-
-Three numbered steps, bash only — no prose in between:
-
-```bash
-# 1 — Install
-pip install "headroom-ai[all]" # Python
-npm install headroom-ai # Node / TypeScript
-
-# 2 — Pick your mode
-headroom wrap claude # wrap a coding agent
-headroom proxy --port 8787 # drop-in proxy, zero code changes
-# or: from headroom import compress # inline library
-
-# 3 — See the savings
-headroom stats
-```
-
-One-liner extras note below the block:
-`Granular extras: [proxy], [mcp], [ml], [agno], [langchain], [evals]. Requires Python 3.10+`
-
----
-
-### 9. Proof
-
-Keep both existing tables verbatim (workloads savings + accuracy benchmarks).
-Keep `headroom-savings.png` with the leaderboard link.
-Keep the reproduce snippet: `python -m headroom.evals suite --tier 1`
-
----
-
-### 10. Agent compatibility matrix
-
-Replace the current verbose "Notes" column with ≤5-word entries. Add a `●` column for wrap support.
-
-| Agent | `headroom wrap` | Notes |
-|---|:---:|---|
-| Claude Code | ● | `--memory` · `--code-graph` |
-| Codex | ● | shares memory with Claude |
-| Cursor | ● | prints config — paste once |
-| Aider | ● | starts proxy + launches |
-| Copilot CLI | ● | starts proxy + launches |
-| OpenClaw | ● | installs as ContextEngine plugin |
-
-Footer note: *Any OpenAI-compatible client works via `headroom proxy`.*
-
----
-
-### 11. When to use · When to skip *(new section)*
-
-**Great fit if you…**
-- run AI coding agents daily and want savings without changing your code
-- work across multiple agents and want shared memory
-- need reversible compression — originals always retrievable via CCR
-
-**Skip it if you…**
-- only use a single provider's native compaction and don't need cross-agent memory
-- work in a sandboxed environment where local processes can't run
-
----
-
-### 12. Three `` blocks
-
-Each collapsed by default. Exact `` labels specified below.
-
-**a. `Integrations — drop Headroom into any stack
`**
-Copy the current `` block with heading "Drop Headroom into any stack" (lines ~196–213 of current README) verbatim — the integrations table is already inside a `` today.
-
-**b. `What's inside
`**
-Copy the current `` block with heading "What's inside" (lines ~215–228 of current README) verbatim — SmartCrusher, CodeCompressor, Kompress-base, image compression, CacheAligner, IntelligentContext, CCR, cross-agent memory, SharedContext, `headroom learn`.
-
-**c. `Pipeline internals
`**
-Move the "Canonical pipeline lifecycle" section (lines ~107–135 of current README, beginning "Headroom now exposes one stable request lifecycle…") and the "Provider slices" section (lines ~137–148, beginning "Provider and tool-specific behavior…") here. Content unchanged — just relocated out of the main body.
-
----
-
-### 13. Install
-
-Keep current `pip` / `npm` / `docker` block verbatim.
-Keep extras and Python version note.
-**Note:** Both §8 (quick-start 60-second block) and §13 (full install matrix with docker + extras) are intentional and survive. §8 is the happy path; §13 is the complete reference.
-
----
-
-### 14. headroom learn
-
-Keep `headroom_learn.gif` in a slim subsection **immediately before Section 15 (Docs)**,
-under a `## headroom learn` heading. Centered using raw HTML:
-
-```html
-
-
-
-```
-
-One-sentence caption below: *"headroom learn — mines failed sessions, writes corrections to CLAUDE.md / AGENTS.md"*
-
----
-
-### 15. Documentation
-
-Keep current two-column doc links table verbatim.
-
----
-
-### 16. Compared to
-
-Keep current comparison table verbatim.
-Keep attribution paragraph for RTK and lean-ctx.
-
----
-
-### 17. Contributing · Community · License
-
-Contributing bash block unchanged.
-Community bullet list (leaderboard, Discord, Kompress-base) unchanged.
-License line unchanged.
-
----
-
-## What changes vs. today
-
-| Area | Before | After |
-|---|---|---|
-| Logo | Plain `# Headroom` | ASCII block logo (6 rows) |
-| Tagline | 2-sentence paragraph | 1-line centered, below logo |
-| Power stats | None | Centered line below tagline |
-| Nav links | None | `Docs · Install · Proof · Agents · Discord` |
-| Section headings | Flat prose | Time-boxed where helpful |
-| Agent notes | 15–20 word sentences | ≤5 words |
-| Pipeline/provider | In main body (~80 lines) | Collapsed `` |
-| "When to skip" | Missing | Added |
-| GIF placement | Inline, no caption | Centered with token-count caption |
-
-## What does NOT change
-
-- All benchmark numbers and tables
-- All code snippets
-- All existing GIFs (HeadroomDemo-Fast.gif, headroom_learn.gif, headroom-savings.png)
-- Attribution paragraph for RTK and lean-ctx
-- Docs links
-- Contributing / Community / License
-
----
-
-## Non-goals
-
-- No new GIFs or screenshots
-- No 3-column demo table (no 3 separate GIFs available)
-- No rewrite of benchmark methodology
-- No changes to docs site
+ 
+ 
+ 
+ 
+ 
+ 
+