diff --git a/README.md b/README.md
index e2d552843d..3fd2f9867a 100644
--- a/README.md
+++ b/README.md
@@ -6,38 +6,14 @@
 
 # 🚀 OmniRoute — The Free AI Gateway
 
-### Never stop coding. Connect every AI tool to **268 providers** — **90+ free** — through one endpoint.
+<img src="./docs/diagrams/readme-hero.svg" width="100%" alt="OmniRoute — Never stop coding. Every AI tool → 268 providers — 90+ free — through one endpoint. Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini with auto-fallback. ~1.6B documented free tokens/month — up to ~2.1B in your first month with signup credits. RTK + Caveman compression saves 15–95% tokens. 18 routing strategies. $0 to start."/>
 
-**Plug Claude Code, Codex, Cursor, Cline, Copilot & Antigravity into FREE Claude / GPT / Gemini. Auto-fallback.**
-<br/>
-
-**RTK + Caveman compression saves 15–95% tokens. Never hit limits.**
-
-<br/>
-
-**~1.6B documented free tokens/month** — up to **~2.1B in your first month** with signup credits — aggregated across the free tiers, plus a long tail of permanently-free, no-cap providers, and the compression above stretches every one further. ([how we count →](docs/reference/FREE_TIERS.md#tldr--how-much-free-inference-does-omniroute-actually-aggregate))
-
-<br/>
-
-<h3>
-
-⭐ Star the repo if OMNIROUTE helped you save money and make your work easier.
-
-</h3>
+<sub>([how we count →](docs/reference/FREE_TIERS.md#tldr--how-much-free-inference-does-omniroute-actually-aggregate))</sub>
 
 [![Stars](https://img.shields.io/github/stars/diegosouzapw/OmniRoute?style=social)](https://github.com/diegosouzapw/OmniRoute)
 <a href="https://trendshift.io/repositories/23589" target="_blank"><img src="https://trendshift.io/api/badge/repositories/23589" alt="diegosouzapw%2FOmniRoute | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 [![Star History Rank](https://api.star-history.com/badge?repo=diegosouzapw/OmniRoute&theme=dark)](https://www.star-history.com/diegosouzapw/omniroute)
 
-</br>
-
-[![268 AI Providers](https://img.shields.io/badge/268-AI_Providers-6C5CE7?style=for-the-badge)](#-268-ai-providers--90-free)
-[![90+ Free](https://img.shields.io/badge/90%2B-Free_Tiers-00B894?style=for-the-badge)](#-268-ai-providers--90-free)
-[![1.6B Free Tokens/mo](https://img.shields.io/badge/1.6B-Free_Tokens%2Fmo-00B894?style=for-the-badge)](docs/reference/FREE_TIERS.md)
-[![Token Savings](https://img.shields.io/badge/up_to_95%25-Token_Savings-E17055?style=for-the-badge)](#%EF%B8%8F-save-1595-tokens--automatically)
-[![18 Strategies](https://img.shields.io/badge/18-Routing_Strategies-0984E3?style=for-the-badge)](#-combos--the-flagship)
-[![$0 to start](https://img.shields.io/badge/%240-To_Start-FDCB6E?style=for-the-badge&logoColor=black)](#-quick-start)
-
 <br/>
 
 ### 💬 Join the community
@@ -144,20 +120,7 @@
 
 </div>
 
-> One endpoint. **268 providers.** Never stop building — and let OmniRoute pick the cheapest one that works.
-
-<table>
-  <tr>
-    <td width="33%" valign="top"><b>🚫 Never hit limits</b><br/><sub>Auto-fallback across 268 providers in milliseconds. Quota out? Next provider takes over — zero downtime.</sub></td>
-    <td width="33%" valign="top"><b>💸 Save up to 95% tokens</b><br/><sub>RTK + Caveman stacked compression cuts 15–95% of eligible tokens (~89% avg on tool-heavy sessions).</sub></td>
-    <td width="33%" valign="top"><b>🆓 $0 to start</b><br/><sub>90+ providers with a free tier, 40+ free <i>forever</i> (Qoder, Pollinations, Cloudflare, SiliconFlow…). No card needed.</sub></td>
-  </tr>
-  <tr>
-    <td width="33%" valign="top"><b>🔌 Every tool works</b><br/><sub>26 coding agents — Claude Code, Codex, Cursor, Cline, Copilot, Antigravity — through one config.</sub></td>
-    <td width="33%" valign="top"><b>🧩 One endpoint</b><br/><sub>OpenAI ↔ Claude ↔ Gemini ↔ Responses API translation. Point any tool at <code>/v1</code> and it just works.</sub></td>
-    <td width="33%" valign="top"><b>🛡️ Production-grade</b><br/><sub>Circuit breakers, TLS stealth, MCP (104 tools), A2A, memory, guardrails, evals. 25,000+ tests.</sub></td>
-  </tr>
-</table>
+<img src="./docs/diagrams/promise-pillars.svg" width="100%" alt="The Promise — One endpoint. 268 providers. Never stop building — OmniRoute picks the cheapest one that works. Six pillars: Never hit limits (auto-fallback across 268 providers in milliseconds, zero downtime) · Save up to 95% tokens (RTK + Caveman stacked compression cuts 15–95%, ~89% avg on tool-heavy sessions) · $0 to start (90+ free tiers, 40+ free forever — no card needed) · Every tool works (26 coding agents through one config) · One endpoint (OpenAI ↔ Claude ↔ Gemini ↔ Responses API at /v1) · Production-grade (circuit breakers, TLS stealth, MCP 104 tools, A2A, memory, guardrails, evals — 25,000+ tests)."/>
 
 <br/>
 <br/>
@@ -279,10 +242,10 @@ All **18** strategies — mix & match per combo step:
 | Feature                                | OmniRoute                                                           | Other routers |
 | -------------------------------------- | ------------------------------------------------------------------- | ------------- |
 | 🌐 Providers                           | **268**                                                             | 20–100        |
-| 🆓 Free providers                      | **90+ (40+ free forever)**                                           | 1–5           |
+| 🆓 Free providers                      | **90+ (40+ free forever)**                                          | 1–5           |
 | 🔀 Routing strategies                  | **18** (priority, weighted, cost-optimized, context-relay, fusion…) | 1–3           |
 | 🗜️ Token compression                   | **RTK + Caveman stacked (15–95%)**                                  | None / 20–40% |
-| 🧰 Built-in MCP server                 | **104 tools, 3 transports, 30 scopes**                               | Rare          |
+| 🧰 Built-in MCP server                 | **104 tools, 3 transports, 30 scopes**                              | Rare          |
 | 🤝 A2A agent protocol                  | **6 skills, JSON-RPC 2.0**                                          | None          |
 | 🧠 Memory (FTS5 + vector)              | **Yes**                                                             | Rare          |
 | 🛡️ Guardrails (PII, injection, vision) | **Yes**                                                             | Rare          |
@@ -517,12 +480,12 @@ Tokens are scoped `read` / `write` / `admin`; process-spawning routes stay loopb
 
 Expose OmniRoute over **MCP** or **A2A** and any capable agent gets the keys to the whole gateway — routing, providers, combos, cache, compression, memory — autonomously.
 
-| Protocol           | Endpoint                                        | Use it for                                             |
-| ------------------ | ----------------------------------------------- | ------------------------------------------------------ |
-| 🧰 **MCP (stdio)** | `omniroute --mcp`                               | Plug into Claude Desktop, Cursor, any MCP client       |
+| Protocol           | Endpoint                                        | Use it for                                              |
+| ------------------ | ----------------------------------------------- | ------------------------------------------------------- |
+| 🧰 **MCP (stdio)** | `omniroute --mcp`                               | Plug into Claude Desktop, Cursor, any MCP client        |
 | 🌊 **MCP (HTTP)**  | `http://localhost:20128/api/mcp/stream`         | Remote MCP — **104 tools**, 30 scopes, full audit trail |
-| 📡 **MCP (SSE)**   | `http://localhost:20128/api/mcp/sse`            | Streaming MCP transport                                |
-| 🤝 **A2A**         | `http://localhost:20128/.well-known/agent.json` | Agent-to-agent, **JSON-RPC 2.0** + SSE, 6 skills       |
+| 📡 **MCP (SSE)**   | `http://localhost:20128/api/mcp/sse`            | Streaming MCP transport                                 |
+| 🤝 **A2A**         | `http://localhost:20128/.well-known/agent.json` | Agent-to-agent, **JSON-RPC 2.0** + SSE, 6 skills        |
 
 ```bash
 # Give Claude Code the full OmniRoute toolset over MCP:
@@ -885,7 +848,7 @@ same process on one port, so there is no separate CLI-only package today.
 | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [API Reference](docs/reference/API_REFERENCE.md)  | All endpoints with examples                                                                                                                                                             |
 | [OpenAPI Spec](docs/openapi.yaml)                 | OpenAPI 3.0 specification                                                                                                                                                               |
-| [MCP Server](open-sse/mcp-server/README.md)       | 104 MCP tools, IDE configs, Python/TS/Go clients                                                                                                                                         |
+| [MCP Server](open-sse/mcp-server/README.md)       | 104 MCP tools, IDE configs, Python/TS/Go clients                                                                                                                                        |
 | [MCP Server Guide](docs/frameworks/MCP-SERVER.md) | MCP installation, transports, and tool reference                                                                                                                                        |
 | [A2A Server](src/lib/a2a/README.md)               | JSON-RPC 2.0 protocol, skills, streaming, task mgmt                                                                                                                                     |
 | [A2A Server Guide](docs/frameworks/A2A-SERVER.md) | A2A agent card, tasks, skills, and streaming                                                                                                                                            |
diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md
index 8f318a5e32..27a6679abc 100644
--- a/docs/diagrams/README.md
+++ b/docs/diagrams/README.md
@@ -27,14 +27,16 @@ Not every diagram comes from a `.mmd` source. Hand-authored SVGs live at this
 directory's root and animate with SMIL only (no JS, no external fonts), so they play
 inside GitHub's `<img>` sandbox:
 
-| File                                     | Used in          | Notes                                                                        |
-| ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------- |
-| [tier-cascade.svg](./tier-cascade.svg)   | README.md (root) | Animated 4-tier auto-fallback cascade (16s loop, 4 acts). Edit the SVG directly — there is no `.mmd` source. |
-| [pool-fair-share.svg](./pool-fair-share.svg) | README.md (root) | Animated key-pool fair-share quota (generous → strict, 16s loop). Edit the SVG directly — there is no `.mmd` source. |
-| [combo-always-on.svg](./combo-always-on.svg) | README.md (root) | Animated priority-combo fallback (4 layers, 16s loop). Edit the SVG directly — there is no `.mmd` source. |
-| [cli-terminal.svg](./cli-terminal.svg) | README.md (root) | Animated terminal cycling 3 CLI commands (providers/combo/health) + subcommand ticker (18s loop). Edit the SVG directly — there is no `.mmd` source. |
-| [compression-pipeline.svg](./compression-pipeline.svg) | README.md (root) | Animated 10-engine compression funnel (8s loop). Edit the SVG directly — there is no `.mmd` source. |
-| [free-tier-budget.svg](./free-tier-budget.svg) | README.md (root) | Animated free-tier budget card (~1.6B/mo headline, 21-pool budget bar, per-model grid, signup credits, 10s loop). Edit the SVG directly — there is no `.mmd` source. |
+| File                                                   | Used in          | Notes                                                                                                                                                                      |
+| ------------------------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [tier-cascade.svg](./tier-cascade.svg)                 | README.md (root) | Animated 4-tier auto-fallback cascade (16s loop, 4 acts). Edit the SVG directly — there is no `.mmd` source.                                                               |
+| [pool-fair-share.svg](./pool-fair-share.svg)           | README.md (root) | Animated key-pool fair-share quota (generous → strict, 16s loop). Edit the SVG directly — there is no `.mmd` source.                                                       |
+| [combo-always-on.svg](./combo-always-on.svg)           | README.md (root) | Animated priority-combo fallback (4 layers, 16s loop). Edit the SVG directly — there is no `.mmd` source.                                                                  |
+| [cli-terminal.svg](./cli-terminal.svg)                 | README.md (root) | Animated terminal cycling 3 CLI commands (providers/combo/health) + subcommand ticker (18s loop). Edit the SVG directly — there is no `.mmd` source.                       |
+| [compression-pipeline.svg](./compression-pipeline.svg) | README.md (root) | Animated 10-engine compression funnel (8s loop). Edit the SVG directly — there is no `.mmd` source.                                                                        |
+| [free-tier-budget.svg](./free-tier-budget.svg)         | README.md (root) | Animated free-tier budget card (~1.6B/mo headline, 21-pool budget bar, per-model grid, signup credits, 10s loop). Edit the SVG directly — there is no `.mmd` source.       |
+| [readme-hero.svg](./readme-hero.svg)                   | README.md (root) | Animated hero card (tagline, 268-provider/90+ free headline, ~1.6B stat, compression bar demo, 6 stat chips, star CTA). Edit the SVG directly — there is no `.mmd` source. |
+| [promise-pillars.svg](./promise-pillars.svg)           | README.md (root) | Animated "The Promise" 6-pillar card (fade-in + 12s border-highlight sweep). Edit the SVG directly — there is no `.mmd` source.                                            |
 
 ## How to update
 
diff --git a/docs/diagrams/promise-pillars.svg b/docs/diagrams/promise-pillars.svg
new file mode 100644
index 0000000000..f883f541fb
--- /dev/null
+++ b/docs/diagrams/promise-pillars.svg
@@ -0,0 +1,161 @@
+<svg viewBox="0 0 1200 540" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="The OmniRoute promise: one endpoint, 268 providers — never stop building, OmniRoute picks the cheapest one that works. Six pillars. Never hit limits: auto-fallback across 268 providers in milliseconds, quota out means the next provider takes over with zero downtime. Save up to 95 percent of tokens: RTK plus Caveman stacked compression cuts 15 to 95 percent of eligible tokens, about 89 percent average on tool-heavy sessions. Zero dollars to start: 90+ providers with a free tier, 40+ free forever — Qoder, Pollinations, Cloudflare, SiliconFlow — no card needed. Every tool works: 26 coding agents including Claude Code, Codex, Cursor, Cline, Copilot and Antigravity through one config. One endpoint: OpenAI, Claude, Gemini and Responses API translation — point any tool at /v1 and it just works. Production-grade: circuit breakers, TLS stealth, MCP with 104 tools, A2A, memory, guardrails, evals — 25,000+ tests.">
+  <desc>Animated promise card: six pillar tiles fade in in reading order, then a soft colored border highlight sweeps from tile to tile in a continuous cycle.</desc>
+  <defs>
+    <pattern id="gridPaperP" width="32" height="32" patternUnits="userSpaceOnUse">
+      <path d="M 32 0 L 0 0 0 32" fill="none" stroke="#ffffff" stroke-opacity="0.06" stroke-width="1"/>
+    </pattern>
+    <radialGradient id="bgGlowP" cx="70%" cy="14%" r="55%">
+      <stop offset="0%" stop-color="#e54d5e" stop-opacity="0.12"/>
+      <stop offset="55%" stop-color="#8b5cf6" stop-opacity="0.06"/>
+      <stop offset="100%" stop-color="#6366f1" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="gradBrandP" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#e54d5e"/>
+      <stop offset="100%" stop-color="#a855f7"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="1200" height="540" fill="#0b0e14"/>
+  <rect width="1200" height="540" fill="url(#gridPaperP)"/>
+  <rect width="1200" height="540" fill="url(#bgGlowP)"/>
+  <rect x="1.5" y="1.5" width="1197" height="537" rx="18" fill="none" stroke="#232b38" stroke-width="3"/>
+  <rect x="0" y="0" width="1200" height="6" fill="url(#gradBrandP)"/>
+
+  <!-- header -->
+  <g opacity="0">
+    <animate attributeName="opacity" from="0" to="1" begin="0.1s" dur="0.5s" fill="freeze"/>
+    <text x="40" y="58" font-family="Consolas, 'Courier New', monospace" font-size="13" letter-spacing="2.5" fill="#a78bfa">THE PROMISE</text>
+    <line x1="150" y1="53" x2="1160" y2="53" stroke="#232b38" stroke-width="1.5"/>
+  </g>
+  <g opacity="0" transform="translate(0,10)">
+    <animate attributeName="opacity" from="0" to="1" begin="0.3s" dur="0.6s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+    <animateTransform attributeName="transform" type="translate" from="0 10" to="0 0" begin="0.3s" dur="0.6s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+    <text x="40" y="100" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="23" font-weight="600" fill="#c9d1d9">One endpoint. <tspan fill="#a78bfa" font-weight="800">268 providers.</tspan> Never stop building — OmniRoute picks <tspan fill="#7ee787" font-weight="700">the cheapest one that works</tspan>.</text>
+  </g>
+
+  <g font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif">
+
+    <!-- cell 1: never hit limits (blue) -->
+    <g opacity="0" transform="translate(0,12)">
+      <animate attributeName="opacity" from="0" to="1" begin="0.55s" dur="0.5s" fill="freeze"/>
+      <animateTransform attributeName="transform" type="translate" from="0 12" to="0 0" begin="0.55s" dur="0.5s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+      <rect x="40" y="130" width="360" height="164" rx="14" fill="#161c28" stroke="#232b38" stroke-width="1.5"/>
+      <rect x="40" y="130" width="360" height="164" rx="14" fill="none" stroke="#74b9ff" stroke-width="1.5" opacity="0">
+        <animate attributeName="opacity" values="0;0.9;0;0" keyTimes="0;0.055;0.12;1" dur="12s" begin="3s" repeatCount="indefinite"/>
+      </rect>
+      <rect x="40" y="146" width="4" height="132" rx="2" fill="#0984e3"/>
+      <g transform="translate(66,152)" stroke="#74b9ff" stroke-width="2.4" fill="none" stroke-linecap="round">
+        <circle cx="11" cy="11" r="10.5"/>
+        <line x1="3.9" y1="3.9" x2="18.1" y2="18.1"/>
+      </g>
+      <text x="102" y="170" font-size="18" font-weight="800" fill="#74b9ff">Never hit limits</text>
+      <text x="66" y="204" font-size="13.5" fill="#a1a1aa">Auto-fallback across 268 providers in</text>
+      <text x="66" y="226" font-size="13.5" fill="#a1a1aa">milliseconds. Quota out? The next provider</text>
+      <text x="66" y="248" font-size="13.5" fill="#a1a1aa">takes over — zero downtime.</text>
+    </g>
+
+    <!-- cell 2: save tokens (orange) -->
+    <g opacity="0" transform="translate(0,12)">
+      <animate attributeName="opacity" from="0" to="1" begin="0.67s" dur="0.5s" fill="freeze"/>
+      <animateTransform attributeName="transform" type="translate" from="0 12" to="0 0" begin="0.67s" dur="0.5s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+      <rect x="420" y="130" width="360" height="164" rx="14" fill="#161c28" stroke="#232b38" stroke-width="1.5"/>
+      <rect x="420" y="130" width="360" height="164" rx="14" fill="none" stroke="#e17055" stroke-width="1.5" opacity="0">
+        <animate attributeName="opacity" values="0;0;0.9;0;0" keyTimes="0;0.167;0.222;0.287;1" dur="12s" begin="3s" repeatCount="indefinite"/>
+      </rect>
+      <rect x="420" y="146" width="4" height="132" rx="2" fill="#e17055"/>
+      <g transform="translate(446,152)" stroke="#e17055" stroke-width="2.4" fill="none" stroke-linecap="round">
+        <circle cx="5.5" cy="5.5" r="4"/>
+        <circle cx="16.5" cy="16.5" r="4"/>
+        <line x1="19" y1="3" x2="3" y2="19"/>
+      </g>
+      <text x="482" y="170" font-size="18" font-weight="800" fill="#e17055">Save up to 95% tokens</text>
+      <text x="446" y="204" font-size="13.5" fill="#a1a1aa">RTK + Caveman stacked compression cuts</text>
+      <text x="446" y="226" font-size="13.5" fill="#a1a1aa">15–95% of eligible tokens — ~89% average</text>
+      <text x="446" y="248" font-size="13.5" fill="#a1a1aa">on tool-heavy sessions.</text>
+    </g>
+
+    <!-- cell 3: $0 to start (gold) -->
+    <g opacity="0" transform="translate(0,12)">
+      <animate attributeName="opacity" from="0" to="1" begin="0.79s" dur="0.5s" fill="freeze"/>
+      <animateTransform attributeName="transform" type="translate" from="0 12" to="0 0" begin="0.79s" dur="0.5s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+      <rect x="800" y="130" width="360" height="164" rx="14" fill="#161c28" stroke="#232b38" stroke-width="1.5"/>
+      <rect x="800" y="130" width="360" height="164" rx="14" fill="none" stroke="#fdcb6e" stroke-width="1.5" opacity="0">
+        <animate attributeName="opacity" values="0;0;0.9;0;0" keyTimes="0;0.334;0.389;0.454;1" dur="12s" begin="3s" repeatCount="indefinite"/>
+      </rect>
+      <rect x="800" y="146" width="4" height="132" rx="2" fill="#fdcb6e"/>
+      <g transform="translate(826,152)" stroke="#fdcb6e" stroke-width="2.2" fill="none" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M 2,9.5 L 2,3 A 1,1 0 0 1 3,2 L 9.5,2 L 20,12.5 A 1.6,1.6 0 0 1 20,14.8 L 14.8,20 A 1.6,1.6 0 0 1 12.5,20 Z"/>
+        <circle cx="6.6" cy="6.6" r="1.4" fill="#fdcb6e" stroke="none"/>
+      </g>
+      <text x="862" y="170" font-size="18" font-weight="800" fill="#fdcb6e">$0 to start</text>
+      <text x="826" y="204" font-size="13.5" fill="#a1a1aa">90+ providers with a free tier, 40+ free</text>
+      <text x="826" y="226" font-size="13.5" fill="#a1a1aa">forever — Qoder, Pollinations, Cloudflare,</text>
+      <text x="826" y="248" font-size="13.5" fill="#a1a1aa">SiliconFlow… No card needed.</text>
+    </g>
+
+    <!-- cell 4: every tool works (violet) -->
+    <g opacity="0" transform="translate(0,12)">
+      <animate attributeName="opacity" from="0" to="1" begin="0.91s" dur="0.5s" fill="freeze"/>
+      <animateTransform attributeName="transform" type="translate" from="0 12" to="0 0" begin="0.91s" dur="0.5s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+      <rect x="40" y="314" width="360" height="164" rx="14" fill="#161c28" stroke="#232b38" stroke-width="1.5"/>
+      <rect x="40" y="314" width="360" height="164" rx="14" fill="none" stroke="#a78bfa" stroke-width="1.5" opacity="0">
+        <animate attributeName="opacity" values="0;0;0.9;0;0" keyTimes="0;0.5;0.555;0.62;1" dur="12s" begin="3s" repeatCount="indefinite"/>
+      </rect>
+      <rect x="40" y="330" width="4" height="132" rx="2" fill="#8b5cf6"/>
+      <g transform="translate(66,336)" stroke="#a78bfa" stroke-width="2.2" fill="none" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M 6,2 L 6,7 M 14,2 L 14,7"/>
+        <path d="M 3.5,7 L 16.5,7 L 16.5,11.5 A 6.5,6.5 0 0 1 10,18 A 6.5,6.5 0 0 1 3.5,11.5 Z"/>
+        <path d="M 10,18 L 10,22"/>
+      </g>
+      <text x="102" y="354" font-size="18" font-weight="800" fill="#a78bfa">Every tool works</text>
+      <text x="66" y="388" font-size="13.5" fill="#a1a1aa">26 coding agents — Claude Code, Codex,</text>
+      <text x="66" y="410" font-size="13.5" fill="#a1a1aa">Cursor, Cline, Copilot, Antigravity —</text>
+      <text x="66" y="432" font-size="13.5" fill="#a1a1aa">through one config.</text>
+    </g>
+
+    <!-- cell 5: one endpoint (cyan) -->
+    <g opacity="0" transform="translate(0,12)">
+      <animate attributeName="opacity" from="0" to="1" begin="1.03s" dur="0.5s" fill="freeze"/>
+      <animateTransform attributeName="transform" type="translate" from="0 12" to="0 0" begin="1.03s" dur="0.5s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+      <rect x="420" y="314" width="360" height="164" rx="14" fill="#161c28" stroke="#232b38" stroke-width="1.5"/>
+      <rect x="420" y="314" width="360" height="164" rx="14" fill="none" stroke="#00cec9" stroke-width="1.5" opacity="0">
+        <animate attributeName="opacity" values="0;0;0.9;0;0" keyTimes="0;0.667;0.722;0.787;1" dur="12s" begin="3s" repeatCount="indefinite"/>
+      </rect>
+      <rect x="420" y="330" width="4" height="132" rx="2" fill="#00cec9"/>
+      <g transform="translate(446,336)" stroke="#00cec9" stroke-width="2.2" fill="none" stroke-linecap="round">
+        <path d="M 2,3 L 13,8.5 M 2,11 L 13,11 M 2,19 L 13,13.5"/>
+        <circle cx="18.5" cy="11" r="3.2" fill="#00cec9" stroke="none"/>
+      </g>
+      <text x="482" y="354" font-size="18" font-weight="800" fill="#00cec9">One endpoint</text>
+      <text x="446" y="388" font-size="13.5" fill="#a1a1aa">OpenAI ↔ Claude ↔ Gemini ↔ Responses API</text>
+      <text x="446" y="410" font-size="13.5" fill="#a1a1aa">translation. Point any tool at /v1 —</text>
+      <text x="446" y="432" font-size="13.5" fill="#a1a1aa">it just works.</text>
+    </g>
+
+    <!-- cell 6: production-grade (green) -->
+    <g opacity="0" transform="translate(0,12)">
+      <animate attributeName="opacity" from="0" to="1" begin="1.15s" dur="0.5s" fill="freeze"/>
+      <animateTransform attributeName="transform" type="translate" from="0 12" to="0 0" begin="1.15s" dur="0.5s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+      <rect x="800" y="314" width="360" height="164" rx="14" fill="#161c28" stroke="#232b38" stroke-width="1.5"/>
+      <rect x="800" y="314" width="360" height="164" rx="14" fill="none" stroke="#7ee787" stroke-width="1.5" opacity="0">
+        <animate attributeName="opacity" values="0;0;0.9;0;0" keyTimes="0;0.834;0.889;0.954;1" dur="12s" begin="3s" repeatCount="indefinite"/>
+      </rect>
+      <rect x="800" y="330" width="4" height="132" rx="2" fill="#22c55e"/>
+      <g transform="translate(826,336)" stroke="#7ee787" stroke-width="2.2" fill="none" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M 11,1.5 L 19.5,5 L 19.5,11 C 19.5,16.5 16,19.8 11,21.5 C 6,19.8 2.5,16.5 2.5,11 L 2.5,5 Z"/>
+        <path d="M 7,11 L 10,14 L 15.4,8.2"/>
+      </g>
+      <text x="862" y="354" font-size="18" font-weight="800" fill="#7ee787">Production-grade</text>
+      <text x="826" y="388" font-size="13.5" fill="#a1a1aa">Circuit breakers, TLS stealth, MCP (104</text>
+      <text x="826" y="410" font-size="13.5" fill="#a1a1aa">tools), A2A, memory, guardrails, evals —</text>
+      <text x="826" y="432" font-size="13.5" fill="#a1a1aa">25,000+ tests.</text>
+    </g>
+  </g>
+
+  <!-- footer -->
+  <g opacity="0">
+    <animate attributeName="opacity" from="0" to="1" begin="1.5s" dur="0.6s" fill="freeze"/>
+    <text x="40" y="516" font-family="Consolas, 'Courier New', monospace" font-size="12" fill="#71717a">$ npm i -g omniroute&#160;&#160;·&#160;&#160;point your tool at http://localhost:20128/v1&#160;&#160;·&#160;&#160;$0</text>
+    <text x="1160" y="516" text-anchor="end" font-family="Consolas, 'Courier New', monospace" font-size="12" letter-spacing="1.5" fill="#71717a">MIT · OPEN SOURCE</text>
+  </g>
+</svg>
diff --git a/docs/diagrams/readme-hero.svg b/docs/diagrams/readme-hero.svg
new file mode 100644
index 0000000000..8f040fe86e
--- /dev/null
+++ b/docs/diagrams/readme-hero.svg
@@ -0,0 +1,154 @@
+<svg viewBox="0 0 1200 640" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="OmniRoute hero: Never stop coding. Connect every AI tool to 268 providers — 90+ free — through one endpoint. Plug Claude Code, Codex, Cursor, Cline, Copilot and Antigravity into free Claude, GPT and Gemini with auto-fallback. About 1.6 billion documented free tokens per month — up to about 2.1 billion in your first month with signup credits — plus a long tail of permanently-free no-cap providers. RTK + Caveman stacked compression saves 15 to 95 percent of tokens so you never hit limits. Stats: 268 AI providers, 90+ free tiers, about 1.6B free tokens per month, 15 to 95 percent token savings, 18 routing strategies, zero dollars to start. Star the repo if OmniRoute helped you save money and make your work easier.">
+  <desc>Animated hero card: the tagline, provider stats, free-token headline and stat chips fade in in sequence; a compression bar repeatedly shrinks a prompt by up to 95 percent, a pulse travels the divider and the star gently twinkles.</desc>
+  <defs>
+    <pattern id="gridPaperH" width="32" height="32" patternUnits="userSpaceOnUse">
+      <path d="M 32 0 L 0 0 0 32" fill="none" stroke="#ffffff" stroke-opacity="0.06" stroke-width="1"/>
+    </pattern>
+    <radialGradient id="bgGlowH" cx="24%" cy="20%" r="55%">
+      <stop offset="0%" stop-color="#e54d5e" stop-opacity="0.14"/>
+      <stop offset="55%" stop-color="#8b5cf6" stop-opacity="0.06"/>
+      <stop offset="100%" stop-color="#6366f1" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="gradBrandH" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#e54d5e"/>
+      <stop offset="100%" stop-color="#a855f7"/>
+    </linearGradient>
+    <linearGradient id="gradTokenH" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#7ee787"/>
+      <stop offset="100%" stop-color="#22c55e"/>
+    </linearGradient>
+    <radialGradient id="statGlowH" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#22c55e" stop-opacity="0.16"/>
+      <stop offset="100%" stop-color="#22c55e" stop-opacity="0"/>
+    </radialGradient>
+    <path id="dividerPathH" d="M 48,252 L 1152,252"/>
+  </defs>
+
+  <rect width="1200" height="640" fill="#0b0e14"/>
+  <rect width="1200" height="640" fill="url(#gridPaperH)"/>
+  <rect width="1200" height="640" fill="url(#bgGlowH)"/>
+  <rect x="1.5" y="1.5" width="1197" height="637" rx="18" fill="none" stroke="#232b38" stroke-width="3"/>
+  <rect x="0" y="0" width="1200" height="6" fill="url(#gradBrandH)"/>
+
+  <!-- kicker -->
+  <g opacity="0">
+    <animate attributeName="opacity" from="0" to="1" begin="0.1s" dur="0.5s" fill="freeze"/>
+    <text x="48" y="66" font-family="Consolas, 'Courier New', monospace" font-size="13" letter-spacing="2.5" fill="#a78bfa">OMNIROUTE — THE FREE AI GATEWAY</text>
+    <text x="1152" y="66" text-anchor="end" font-family="Consolas, 'Courier New', monospace" font-size="12" letter-spacing="1.5" fill="#71717a">ONE ENDPOINT · /v1</text>
+  </g>
+
+  <!-- tagline -->
+  <g opacity="0" transform="translate(0,14)">
+    <animate attributeName="opacity" from="0" to="1" begin="0.25s" dur="0.6s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+    <animateTransform attributeName="transform" type="translate" from="0 14" to="0 0" begin="0.25s" dur="0.6s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+    <text x="48" y="138" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="60" font-weight="800" fill="#e9edf3">Never stop coding<tspan fill="#a855f7">.</tspan></text>
+  </g>
+
+  <!-- subheadline -->
+  <g opacity="0" transform="translate(0,12)">
+    <animate attributeName="opacity" from="0" to="1" begin="0.5s" dur="0.6s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+    <animateTransform attributeName="transform" type="translate" from="0 12" to="0 0" begin="0.5s" dur="0.6s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+    <text x="48" y="184" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="25" font-weight="600" fill="#c9d1d9">Every AI tool → <tspan fill="#a78bfa" font-weight="800">268 providers</tspan> — <tspan fill="#7ee787" font-weight="800">90+ free</tspan> — through one endpoint.</text>
+  </g>
+
+  <!-- plug line -->
+  <g opacity="0" transform="translate(0,10)">
+    <animate attributeName="opacity" from="0" to="1" begin="0.7s" dur="0.6s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+    <animateTransform attributeName="transform" type="translate" from="0 10" to="0 0" begin="0.7s" dur="0.6s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+    <text x="48" y="222" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="16.5" fill="#a1a1aa">Claude Code · Codex · Cursor · Cline · Copilot · Antigravity&#160;&#160;→&#160;&#160;<tspan fill="#7ee787" font-weight="700">FREE</tspan> Claude / GPT / Gemini · auto-fallback</text>
+  </g>
+
+  <!-- divider + traveling pulse -->
+  <line x1="48" y1="252" x2="1152" y2="252" stroke="#232b38" stroke-width="1.5"/>
+  <circle r="4" fill="url(#gradBrandH)" opacity="0">
+    <animateMotion dur="6s" repeatCount="indefinite" keyPoints="0;1" keyTimes="0;1" calcMode="linear">
+      <mpath href="#dividerPathH"/>
+    </animateMotion>
+    <animate attributeName="opacity" values="0;0.9;0.9;0" keyTimes="0;0.08;0.6;0.75" dur="6s" repeatCount="indefinite"/>
+  </circle>
+
+  <!-- 1.6B stat block -->
+  <g opacity="0">
+    <animate attributeName="opacity" from="0" to="1" begin="1.0s" dur="0.7s" fill="freeze"/>
+    <ellipse cx="200" cy="360" rx="230" ry="110" fill="url(#statGlowH)"/>
+    <text x="48" y="392" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="84" font-weight="800" fill="url(#gradTokenH)">~1.6B</text>
+    <text x="340" y="336" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="20" font-weight="700" fill="#e9edf3">documented free tokens / month</text>
+    <text x="340" y="364" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="15" fill="#a1a1aa">up to <tspan fill="#7ee787" font-weight="700">~2.1B in your first month</tspan> with signup credits</text>
+    <text x="340" y="387" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="13" fill="#71717a">+ a long tail of permanently-free, no-cap providers</text>
+    <text x="340" y="407" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="13" fill="#71717a">honest, pool-deduped math — each shared pool counted once</text>
+  </g>
+
+  <!-- compression panel -->
+  <g opacity="0" transform="translate(0,10)">
+    <animate attributeName="opacity" from="0" to="1" begin="1.25s" dur="0.6s" fill="freeze"/>
+    <animateTransform attributeName="transform" type="translate" from="0 10" to="0 0" begin="1.25s" dur="0.6s" calcMode="spline" keyTimes="0;1" keySplines="0.16 1 0.3 1" fill="freeze"/>
+    <rect x="756" y="284" width="396" height="140" rx="14" fill="#1c2230" stroke="#232b38" stroke-width="1.5"/>
+    <text x="780" y="314" font-family="Consolas, 'Courier New', monospace" font-size="11" letter-spacing="2" fill="#e17055">RTK + CAVEMAN · STACKED COMPRESSION</text>
+    <text x="780" y="344" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="22" font-weight="800" fill="#e9edf3">Save 15–95% tokens</text>
+    <!-- live bar demo -->
+    <rect x="780" y="362" width="348" height="12" rx="6" fill="#0b0e14" stroke="#232b38" stroke-width="1"/>
+    <rect x="780" y="362" width="348" height="12" rx="6" fill="#e17055">
+      <animate attributeName="width" values="348;348;38;38;348" keyTimes="0;0.12;0.5;0.88;1" dur="8s" repeatCount="indefinite" calcMode="spline" keySplines="0.4 0 0.2 1;0.4 0 0.2 1;0.4 0 0.2 1;0.4 0 0.2 1"/>
+    </rect>
+    <text x="780" y="404" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="13" fill="#a1a1aa">your prompt
+      <animate attributeName="opacity" values="1;1;0;0;1" keyTimes="0;0.12;0.35;0.88;1" dur="8s" repeatCount="indefinite" calcMode="discrete"/>
+    </text>
+    <text x="780" y="404" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="13" font-weight="700" fill="#e17055" opacity="0">−89% avg on tool-heavy sessions
+      <animate attributeName="opacity" values="0;0;1;1;0" keyTimes="0;0.35;0.36;0.88;1" dur="8s" repeatCount="indefinite" calcMode="discrete"/>
+    </text>
+    <text x="1128" y="404" text-anchor="end" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="13" fill="#71717a">never hit limits</text>
+  </g>
+
+  <!-- stat chips -->
+  <g font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" text-anchor="middle">
+    <g opacity="0">
+      <animate attributeName="opacity" from="0" to="1" begin="1.5s" dur="0.45s" fill="freeze"/>
+      <rect x="48" y="462" width="172" height="52" rx="12" fill="#1c2230" stroke="#6c5ce7" stroke-opacity="0.55" stroke-width="1.5"/>
+      <text x="134" y="485" font-size="17" font-weight="800" fill="#a78bfa">268</text>
+      <text x="134" y="504" font-size="11" fill="#a1a1aa">AI PROVIDERS</text>
+    </g>
+    <g opacity="0">
+      <animate attributeName="opacity" from="0" to="1" begin="1.62s" dur="0.45s" fill="freeze"/>
+      <rect x="234" y="462" width="172" height="52" rx="12" fill="#1c2230" stroke="#22c55e" stroke-opacity="0.55" stroke-width="1.5"/>
+      <text x="320" y="485" font-size="17" font-weight="800" fill="#7ee787">90+</text>
+      <text x="320" y="504" font-size="11" fill="#a1a1aa">FREE TIERS</text>
+    </g>
+    <g opacity="0">
+      <animate attributeName="opacity" from="0" to="1" begin="1.74s" dur="0.45s" fill="freeze"/>
+      <rect x="420" y="462" width="172" height="52" rx="12" fill="#1c2230" stroke="#22c55e" stroke-opacity="0.55" stroke-width="1.5"/>
+      <text x="506" y="485" font-size="17" font-weight="800" fill="#7ee787">~1.6B</text>
+      <text x="506" y="504" font-size="11" fill="#a1a1aa">FREE TOKENS / MO</text>
+    </g>
+    <g opacity="0">
+      <animate attributeName="opacity" from="0" to="1" begin="1.86s" dur="0.45s" fill="freeze"/>
+      <rect x="606" y="462" width="172" height="52" rx="12" fill="#1c2230" stroke="#e17055" stroke-opacity="0.55" stroke-width="1.5"/>
+      <text x="692" y="485" font-size="17" font-weight="800" fill="#e17055">15–95%</text>
+      <text x="692" y="504" font-size="11" fill="#a1a1aa">TOKEN SAVINGS</text>
+    </g>
+    <g opacity="0">
+      <animate attributeName="opacity" from="0" to="1" begin="1.98s" dur="0.45s" fill="freeze"/>
+      <rect x="792" y="462" width="172" height="52" rx="12" fill="#1c2230" stroke="#0984e3" stroke-opacity="0.55" stroke-width="1.5"/>
+      <text x="878" y="485" font-size="17" font-weight="800" fill="#74b9ff">18</text>
+      <text x="878" y="504" font-size="11" fill="#a1a1aa">ROUTING STRATEGIES</text>
+    </g>
+    <g opacity="0">
+      <animate attributeName="opacity" from="0" to="1" begin="2.1s" dur="0.45s" fill="freeze"/>
+      <rect x="978" y="462" width="174" height="52" rx="12" fill="#1c2230" stroke="#fdcb6e" stroke-opacity="0.55" stroke-width="1.5"/>
+      <text x="1065" y="485" font-size="17" font-weight="800" fill="#fdcb6e">$0</text>
+      <text x="1065" y="504" font-size="11" fill="#a1a1aa">TO START</text>
+    </g>
+  </g>
+
+  <!-- star CTA -->
+  <g opacity="0">
+    <animate attributeName="opacity" from="0" to="1" begin="2.4s" dur="0.6s" fill="freeze"/>
+    <g transform="translate(58,570)">
+      <path d="M 0,-11 L 3.1,-3.6 L 11,-3.2 L 4.9,1.9 L 6.9,9.6 L 0,5.2 L -6.9,9.6 L -4.9,1.9 L -11,-3.2 L -3.1,-3.6 Z" fill="#fdcb6e">
+        <animateTransform attributeName="transform" type="scale" values="1;1.22;1" keyTimes="0;0.5;1" dur="4s" repeatCount="indefinite" calcMode="spline" keySplines="0.4 0 0.2 1;0.4 0 0.2 1"/>
+        <animate attributeName="opacity" values="0.85;1;0.85" dur="4s" repeatCount="indefinite"/>
+      </path>
+    </g>
+    <text x="82" y="576" font-family="Inter, 'Segoe UI', Arial, Helvetica, system-ui, sans-serif" font-size="15.5" fill="#c9d1d9"><tspan font-weight="700" fill="#e9edf3">Star the repo</tspan> if OmniRoute helped you save money and make your work easier.</text>
+    <text x="1152" y="576" text-anchor="end" font-family="Consolas, 'Courier New', monospace" font-size="12" fill="#71717a">$ npm i -g omniroute</text>
+  </g>
+</svg>