diff --git a/README.md b/README.md
index ed089adfec..13853697cc 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
-
-# ๐ OmniRoute โ The Free AI Gateway
+# ๐ OmniRoute
-### Never stop coding. Save 15-95% eligible tokens with RTK+Caveman compression + **Auto-Combo** intelligent routing to **FREE & low-cost AI models**.
+### **The Free AI Gateway โ one endpoint, 177+ providers, zero downtime.**
-_Auto-Combo uses 7-factor scoring (health, quota, cost, latency, capability, stability, tier) to automatically pick the best model for each request with self-healing fallback._
+**Auto-fallback to free models. Stop coding interruptions. Cut tokens 15-95%.**
-_The most complete open-source AI proxy โ **one endpoint**, **160+ providers**, **13 routing strategies**, zero downtime. Multi-platform: **Web**, **Desktop (Electron)**, **Mobile (PWA + Termux)**. Fully extensible via **MCP Server (37 tools)**, **A2A Protocol**, and **Memory/Skills** systems. Available in **40+ languages**._
+[](https://www.npmjs.com/package/omniroute)
+[](LICENSE)
+[](package.json)
+[](https://github.com/diegosouzapw/OmniRoute)
+[](https://trendshift.io/repositories/23589)
-**Chat Completions โข Responses API โข Embeddings โข Image Generation โข Video โข Music โข Audio Speech/Transcription โข Reranking โข Moderations โข Web Search โข MCP Server โข A2A Protocol โข 4,600+ Tests โข 100% TypeScript**
+[**Website**](https://omniroute.online) ยท [**Quick Start**](#-quick-start) ยท [**Docs**](#-documentation) ยท [**Discord/WhatsApp**](#-community)
-
-
-
-
-
-
๐ฅ Limited offer: Sign up at AgentRouter $100 in free AI credits Access GPT-5, Claude, Gemini, DeepSeek & 100+ models. No credit card required. Claim your credits โ
-
-
-
-
-
-[๐ Quick Start](#-quick-start) โข [๐ก Features](#-key-features) โข [๐๏ธ Compression](#%EF%B8%8F-prompt-compression--save-15-95-eligible-tokens-automatically) โข [๐ฐ Pricing](#-pricing-at-a-glance) โข [๐ฏ Use Cases](#-use-cases--ready-made-combo-playbooks) โข [๐ Proxy](#-bypass-geographic-blocks--use-ai-from-any-country) โข [โ FAQ](#-frequently-asked-questions) โข [๐ Docs](#-documentation) โข [๐ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
+
v3.8.0 ยท MIT ยท Production-ready ยท Self-hosted
+## โก The Pitch (60 seconds)
-๐ **Available in:** ๐บ๐ธ [English](README.md) | ๐ง๐ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐ช๐ธ [Espaรฑol](docs/i18n/es/README.md) | ๐ซ๐ท [Franรงais](docs/i18n/fr/README.md) | ๐ฎ๐น [Italiano](docs/i18n/it/README.md) | ๐ท๐บ [ะ ัััะบะธะน](docs/i18n/ru/README.md) | ๐จ๐ณ [ไธญๆ (็ฎไฝ)](docs/i18n/zh-CN/README.md) | ๐ฉ๐ช [Deutsch](docs/i18n/de/README.md) | ๐ฎ๐ณ [เคนเคฟเคจเฅเคฆเฅ](docs/i18n/in/README.md) | ๐น๐ญ [เนเธเธข](docs/i18n/th/README.md) | ๐บ๐ฆ [ะฃะบัะฐัะฝััะบะฐ](docs/i18n/uk-UA/README.md) | ๐ธ๐ฆ [ุงูุนุฑุจูุฉ](docs/i18n/ar/README.md) | ๐ฏ๐ต [ๆฅๆฌ่ช](docs/i18n/ja/README.md) | ๐ป๐ณ [Tiแบฟng Viแปt](docs/i18n/vi/README.md) | ๐ง๐ฌ [ะัะปะณะฐััะบะธ](docs/i18n/bg/README.md) | ๐ฉ๐ฐ [Dansk](docs/i18n/da/README.md) | ๐ซ๐ฎ [Suomi](docs/i18n/fi/README.md) | ๐ฎ๐ฑ [ืขืืจืืช](docs/i18n/he/README.md) | ๐ญ๐บ [Magyar](docs/i18n/hu/README.md) | ๐ฎ๐ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐ฐ๐ท [ํ๊ตญ์ด](docs/i18n/ko/README.md) | ๐ฒ๐พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐ณ๐ฑ [Nederlands](docs/i18n/nl/README.md) | ๐ณ๐ด [Norsk](docs/i18n/no/README.md) | ๐ต๐น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐ท๐ด [Romรขnฤ](docs/i18n/ro/README.md) | ๐ต๐ฑ [Polski](docs/i18n/pl/README.md) | ๐ธ๐ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐ธ๐ช [Svenska](docs/i18n/sv/README.md) | ๐ต๐ญ [Filipino](docs/i18n/phi/README.md) | ๐จ๐ฟ [ฤeลกtina](docs/i18n/cs/README.md)
+| ๐ฏ The problem | โ
How OmniRoute solves it |
+| ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| Hit rate limits on Claude/GPT? | **Auto-fallback** across 177 providers โ never see a 429 again |
+| Bored of switching API keys? | **One endpoint** (`localhost:20128`) speaks OpenAI, Anthropic, Gemini, Claude Code, Cursor formats |
+| Paying $200/mo for AI? | **11 free providers** + intelligent routing โ most users pay $0 |
+| Tokens too expensive? | **RTK + Caveman compression** saves 15-95% on eligible payloads |
+| Blocked region? | **4-level proxy** (account/provider/combo/global) + **1proxy free marketplace** |
+| Want CLI agents free? | Plug **Cursor, Cline, Codex, Claude Code, Aider, 15+ CLIs** at OmniRoute |
-
-
-
-
-[](https://www.npmjs.com/package/omniroute)
-
-
-
-
-[](https://hub.docker.com/r/diegosouzapw/omniroute)
-
-
-[](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE)
-
-
-
-[](https://github.com/diegosouzapw)
-[](https://github.com/diegosouzapw)
-[](https://omniroute.online)
-[](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t)
-
-
+๐บ **Watch in action:** [Video demo](https://www.youtube.com/@diegosouza-pw)
---
-## ๐ผ๏ธ Main Dashboard
+## ๐ผ๏ธ Dashboard Preview
-
-
-
-Click to see dashboard screenshots Click for more screenshots (Providers, Combos, Memory, MCP, Auditโฆ)
---
-### ๐ค Free AI Provider for your favorite coding agents
-
-_Connect any AI-powered IDE or CLI tool through OmniRoute โ free API gateway for unlimited coding._
-
-
-
-๐ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ one config, unlimited models and quota
-
----
-
-## ๐บ OmniRoute in Action โ Video Guides
-
-
-
-
-
-
-
- ๐ง๐ท Portuguรชs Guia completo do OmniRoute
-
-
-
- ๐บ๐ธ English Complete OmniRoute walkthrough
-
-
-
- ๐ท๐บ ะ ัััะบะธะน ะะพะปะฝะพะต ััะบะพะฒะพะดััะฒะพ ะฟะพ OmniRoute
-
-
-
-
-
-
- Claude Code Anthropic Codex CLI OpenAI Gemini CLI Google Cursor IDE OpenClaw CLI Antigravity VS Code
-
- Cline Extension Continue Extension Kilo Code Extension Kiro AWS IDE OpenCode CLI Droid CLI
-
- AMP CLI Copilot GitHub Windsurf IDE Hermes CLI Qwen CLI Alibaba Custom Any tool
-
-
-๐ Full setup for each tool: [`docs/CLI-TOOLS.md`](docs/CLI-TOOLS.md)
-
----
-
-## ๐ Supported Providers โ 160+
-
-### ๐ OAuth Providers
-
-
-
- Claude Code Anthropic OAuth Antigravity Google OAuth Codex OpenAI OAuth GitHub Copilot GitHub OAuth Cursor Cursor OAuth
-
- Kimi Coding Moonshot OAuth Kilo Code Kilo OAuth Cline Cline OAuth
-
-
-### ๐ Free Providers (No Cost)
-
-
-
- ๐ข Kiro AI Claude Sonnet/Haiku ๐ข Qoder AI Kimi-K2, DeepSeek-R1 ๐ข Pollinations GPT-5, Claude, Llama 4 ๐ข Qwen Code Qwen3 Coder Plus
-
- ๐ข LongCat AI Flash-Lite ๐ข Cloudflare AI 50+ models ๐ข Puter AI GPT-4.1, Claude ๐ข NVIDIA NIM Llama, Mistral
-
-
-### ๐ API Key Providers (120+)
-
-
-
- OpenAI Anthropic Gemini DeepSeek Groq xAI (Grok)
-
- Mistral OpenRouter GLM Kimi MiniMax Fireworks
-
- Together AI Cerebras Cohere NVIDIA Perplexity SiliconFlow
-
- Nebius HuggingFace DeepInfra SambaNova Vertex AI Azure OpenAI
-
- AWS Bedrock Snowflake Databricks Venice.ai AI21 Labs Meta Llama
-
-
-
-...and 90+ more providers
-
-### ๐ Self-Hosted
-
-
-
- LM Studio Ollama vLLM Llamafile Docker Model Runner
-
- NVIDIA Triton XInference oobabooga ComfyUI SD WebUI
-
-
----
-
-## ๐ How It Works
-
-```
-โโโโโโโโโโโโโโโ
-โ Your CLI โ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...)
-โ Tool โ
-โโโโโโโโฌโโโโโโโ
- โ http://localhost:20128/v1
- โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ OmniRoute (Smart Router) โ
-โ โข ๐๏ธ Prompt Compression (save 15-95% eligible) โ
-โ โข Format translation (OpenAI โ Claude โ Gemini) โ
-โ โข Quota tracking + Embeddings + Images โ
-โ โข Auto token refresh + Rate limit management โ
-โโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- โ
- โโโ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI
- โ โ quota exhausted
- โโโ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc.
- โ โ budget limit
- โโโ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M)
- โ โ budget limit
- โโโ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited)
-
-Result: Never stop coding, minimal cost + 15-95% eligible token savings
-```
-
----
-
-## ๐๏ธ Prompt Compression โ Save 15-95% Eligible Tokens Automatically
-
-> **Why use many token when few token do trick?** OmniRoute's built-in compression pipeline reduces token usage before requests reach the provider. It combines ideas from [RTK - Rust Token Killer](https://github.com/rtk-ai/rtk) and [Caveman](https://github.com/JuliusBrussee/caveman) (โญ 51K+).
-
-### How It Works
-
-Every request passes through the compression pipeline **transparently** โ no client changes needed:
-
-```
-โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
-โ Client sends โโโโโโถโ OmniRoute Compression โโโโโโถโ Provider โ
-โ full prompt โ โ Pipeline (7 options) โ โ receives โ
-โ (10,000 tok) โ โ โ โ compressed โ
-โ โ โ ๐ชถ Lite ........... ~15% โ โ (~1,080 tok)โ
-โ โ โ ๐ชจ Standard ....... ~30% โ โ โ
-โ โ โ โก Aggressive ..... ~50% โ โ ๐ฐ up to 95%โ
-โ โ โ ๐ฅ Ultra .......... ~75% โ โ โ
-โ โ โ ๐งฐ RTK ............ 60-90% โ โ โ
-โ โ โ ๐ Stacked ........ 78-95% โ โ โ
-โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
-```
-
-### 7 Compression Options
-
-| Mode | Savings | Technique | Best For |
-| ------------------------- | ------- | ----------------------------------------------------------------------------------------------- | -------------------------------------- |
-| **Off** | 0% | No compression | When you need exact prompts |
-| **๐ชถ Lite** | ~15% | Whitespace collapse, dedup system prompts, image URL shortening | Always-on safe default |
-| **๐ชจ Standard (Caveman)** | ~30% | 30+ regex rules: filler removal, context condensation, structural compression, multi-turn dedup | Daily coding with Claude/Codex |
-| **โก Aggressive** | ~50% | All standard + progressive message aging + tool result summarization + LLM-based compression | Long sessions with many tool calls |
-| **๐ฅ Ultra** | ~75% | All aggressive + heuristic token pruning + stopword removal + score-based filtering | Maximum savings when tokens are scarce |
-| **๐งฐ RTK** | 60-90% | 49 command-aware filters, RTK-style JSON DSL, verify gate, trust-gated custom filters | Shell/test/build/git output in agents |
-| **๐ Stacked** | 78-95% | RTK first, then Caveman input condensation; ~89% with upstream average math | Mixed prompts with tool logs + prose |
-
-### RTK + Caveman Savings Math
-
-These numbers are based on the upstream project READMEs under `_references/_outros`:
-
-| Source | Upstream claim used by OmniRoute docs |
-| ------- | ------------------------------------------------------------------------------------------------------------------- |
-| Caveman | `~75%` fewer output tokens; benchmark average `65%` output savings, range `22-87%`; `~46%` input compression tool |
-| RTK | `60-90%` command-output token savings; sample session `~118,000 -> ~23,900` tokens, which is `79.7%` saved (`~80%`) |
-
-For the default stacked compression combo, OmniRoute runs:
-
-```txt
-RTK -> Caveman
-```
-
-When both engines can act on the same tool/context payload, the savings compound:
-
-```txt
-combined = 1 - (1 - RTK savings) * (1 - Caveman input savings)
-average = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%
-range = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
-```
-
-Caveman output mode is separate from prompt compression. When enabled for responses, use Caveman's
-own upstream output numbers: `65%` average, `~75%` headline, `22-87%` observed range. Total bill
-savings depend on the prompt/output mix, but coding-agent sessions are often tool-context heavy, so
-the `RTK -> Caveman` combo is the best default for maximum context savings.
-
-### Before & After (Standard/Caveman Mode)
-
-**๐ฃ๏ธ Before compression (69 tokens):**
-
-> "The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I would recommend using useMemo to memoize the object."
-
-**๐ชจ After compression (19 tokens):**
-
-> "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."
-
-**Same answer. 72% less tokens. Zero accuracy loss.**
-
-### Architecture
-
-```
-Request Body
- โ
- โโ strategySelector.ts โโโ Picks mode (config / combo override / auto-trigger)
- โ
- โโ lite.ts โโโโโโโโโโโโโโโ Whitespace, dedup, image URLs, redundant content
- โโ caveman.ts โโโโโโโโโโโโ 30+ regex rules via cavemanRules.ts
- โ โโ preservation.ts โโโ Protects code blocks, URLs, JSON from compression
- โโ engines/rtk/ โโโโโโโโโโ Command detection + JSON DSL filters + raw-output recovery
- โโ engines/registry.ts โโโ Shared engine registry for caveman, RTK, and stacked
- โโ aggressive.ts โโโโโโโโโ Summarizer + tool result compressor + progressive aging
- โ โโ summarizer.ts โโโโโ Rule-based message summarization
- โ โโ toolResultCompressor.ts โโ file/grep/shell/JSON/error compression
- โ โโ progressiveAging.ts โโโโ Older messages โ shorter summaries
- โโ ultra.ts โโโโโโโโโโโโโโ Heuristic token scoring + pruning
- โโ ultraHeuristic.ts โ Stopword detection, score thresholds, force-preserve
-```
-
-### Configuration
-
-```
-Dashboard โ Context & Cache โ Caveman / RTK / Compression Combos
-```
-
-Or per-combo override:
-
-```json
-{
- "comboOverrides": {
- "my-coding-combo": "standard",
- "my-cheap-combo": "ultra"
- }
-}
-```
-
-Auto-trigger: set `autoTriggerTokens` to automatically enable compression when a request exceeds a token threshold.
-
-Compression combos can also assign a named compression pipeline to routing combos, so a coding combo can use RTK + Caveman while a paid subscription combo stays on lite mode.
-
-> ๐ชจ **Fun fact:** The standard/caveman mode is inspired by [Caveman](https://github.com/JuliusBrussee/caveman) โ the viral project that reports 65% average output-token savings while keeping technical accuracy. OmniRoute takes this further with a **7-option pipeline** and a default `RTK -> Caveman` combo that can reach ~89% average savings on eligible tool/context payloads.
-
-๐ **Full compression documentation:** [`docs/COMPRESSION_GUIDE.md`](docs/COMPRESSION_GUIDE.md) โข [`docs/RTK_COMPRESSION.md`](docs/RTK_COMPRESSION.md) โข [`docs/COMPRESSION_ENGINES.md`](docs/COMPRESSION_ENGINES.md) โข [`docs/COMPRESSION_RULES_FORMAT.md`](docs/COMPRESSION_RULES_FORMAT.md) โข [`docs/COMPRESSION_LANGUAGE_PACKS.md`](docs/COMPRESSION_LANGUAGE_PACKS.md)
-
----
-
-## ๐ฏ What OmniRoute Solves
-
-> **Every developer using AI tools faces these problems daily.** OmniRoute solves them all.
-
-| # | Problem | OmniRoute Solution |
-| --- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| ๐ธ | Subscription quota expires mid-coding | **Smart 4-Tier Fallback** โ auto-routes Subscription โ API Key โ Cheap โ Free |
-| ๐ | Each provider has a different API format | **Format Translation** โ unified endpoint translates OpenAI โ Claude โ Gemini โ Responses |
-| ๐ | AI providers block my country/region | **3-Level Proxy** โ global, per-provider, and per-key proxy with TLS fingerprint spoofing |
-| ๐ | Can't afford AI subscriptions | **11 Free Providers** โ Kiro, Qoder, Pollinations, LongCat, Cloudflare AI, NVIDIA NIM... |
-| ๐ | Gateway is exposed without protection | **API Key Management** โ scoping, rotation, IP filtering, rate limiting, prompt injection guard |
-| ๐ | Provider went down, lost coding flow | **Circuit Breakers** โ auto-failover with cooldown, retry, anti-thundering herd |
-| ๐ง | Configuring each CLI tool is tedious | **CLI Tools Dashboard** โ one-click setup for Claude Code, Codex, Cursor, OpenClaw, Kilo |
-| ๐ | Managing OAuth tokens is hell | **Auto Token Refresh** โ OAuth PKCE for 8 providers, multi-account, LAN/remote fix |
-| ๐ | Don't know how much I'm spending | **Cost Analytics** โ per-token tracking, budget limits, usage stats per API key |
-| ๐ | Can't diagnose errors in AI calls | **Unified Logs** โ 4-tab dashboard (request, proxy, audit, console) + p50/p95/p99 telemetry |
-
-
-๐ See all 31 problems OmniRoute solves
-
-๐ **Deep dives:** [Resilience Guide](docs/RESILIENCE_GUIDE.md) โข [Proxy Guide](docs/PROXY_GUIDE.md) โข [Setup Guide](docs/SETUP_GUIDE.md) โข [Compression Guide](docs/COMPRESSION_GUIDE.md)
-
----
-
-## ๐ Start Free โ Zero Configuration Cost
-
-> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo.
-
-| Step | Action | Providers Unlocked |
-| ---- | -------------------------------------------------- | ------------------------------------------------------------------ |
-| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ **unlimited** |
-| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ **unlimited** |
-| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ **unlimited** |
-| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ **180K/mo free** |
-| 5 | `/dashboard/combos` โ **Free Stack ($0)** template | Round-robin all free providers automatically |
-
-**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done.
-
-> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models).
-
## โก Quick Start
-### 1) Install and run
-
```bash
-npm install -g omniroute
-omniroute
-```
-
-Dashboard opens at `http://localhost:20128` ยท API at `http://localhost:20128/v1`.
-
-### 2) Connect providers
-
-1. Dashboard โ **Providers** โ connect at least one provider (OAuth or API key)
-2. Dashboard โ **Endpoints** โ create an API key
-3. Dashboard โ **Combos** โ set your fallback chain (optional)
-
-### 3) Point your coding tool
-
-```txt
-Base URL: http://localhost:20128/v1
-API Key: [copy from Endpoint page]
-Model: if/kimi-k2-thinking (or any provider/model)
-```
-
-Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and any OpenAI-compatible tool.
-
-
-๐ฆ More install methods (Docker, source, Arch, Void, pnpm)
-
----
-
-## ๐ณ Docker
-
-OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute).
-
-**Quick run:**
-
-```bash
-docker run -d \
- --name omniroute \
- --restart unless-stopped \
- --stop-timeout 40 \
- -p 20128:20128 \
- -v omniroute-data:/app/data \
- diegosouzapw/omniroute:latest
-```
-
-**With environment file:**
-
-```bash
-# Copy and edit .env first
-cp .env.example .env
-
-docker run -d \
- --name omniroute \
- --restart unless-stopped \
- --stop-timeout 40 \
- --env-file .env \
- -p 20128:20128 \
- -v omniroute-data:/app/data \
- diegosouzapw/omniroute:latest
-```
-
-**Using Docker Compose:**
-
-```bash
-# Base profile (no CLI tools)
-docker compose --profile base up -d
-
-# CLI profile (Claude Code, Codex, OpenClaw built-in)
-docker compose --profile cli up -d
-```
-
-Dashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL. Endpoint tunnel panels, including Cloudflare, Tailscale, and ngrok, can be shown or hidden from `Settings โ Appearance` without changing active tunnel state.
-
-Notes:
-
-- Quick Tunnel URLs are temporary and change after every restart.
-- Quick Tunnels are not auto-restored after an OmniRoute or container restart. Re-enable them from the dashboard when needed.
-- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`.
-- Managed Quick Tunnels default to HTTP/2 transport to avoid noisy QUIC UDP buffer warnings in constrained container environments. Set `CLOUDFLARED_PROTOCOL=quic` or `auto` if you want a different transport.
-- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container.
-- SQLite runs in WAL mode. `docker stop` should be allowed to finish so OmniRoute can checkpoint the latest changes back into `storage.sqlite`.
-- The bundled Compose files already set a 40s stop grace period. If you run the image directly, keep `--stop-timeout 40` (or similar) so manual stops do not cut off shutdown cleanup.
-- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one.
-
-**Using Docker Compose with Caddy (HTTPS Auto-TLS):**
-
-OmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP.
-
-```yaml
-services:
- omniroute:
- image: diegosouzapw/omniroute:latest
- container_name: omniroute
- restart: unless-stopped
- volumes:
- - omniroute-data:/app/data
- environment:
- - PORT=20128
- - NEXT_PUBLIC_BASE_URL=https://your-domain.com
-
- caddy:
- image: caddy:latest
- container_name: caddy
- restart: unless-stopped
- ports:
- - "80:80"
- - "443:443"
- command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128
-
-volumes:
- omniroute-data:
-```
-
-| Image | Tag | Size | Description |
-| ------------------------ | -------- | ------ | --------------------- |
-| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release |
-| `diegosouzapw/omniroute` | `3.7.8` | ~250MB | Current version |
-
-๐ **Full Docker documentation:** [`docs/DOCKER_GUIDE.md`](docs/DOCKER_GUIDE.md) โ Compose profiles, Caddy HTTPS, Cloudflare tunnels, and more.
-
----
-
-## ๐ฑ Multi-Platform โ Run Anywhere
-
-> OmniRoute runs on **Web**, **Desktop (Electron)**, **Android (Termux)**, and as a **Progressive Web App (PWA)**.
-
-| Platform | Install | Highlights |
-| -------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
-| ๐ฅ๏ธ **Desktop** | `npm run electron:build` | Native window, system tray, auto-start, offline mode โ Windows/macOS/Linux |
-| ๐ฑ **Android** | `pkg install nodejs-lts && npx -y omniroute` | ARM native, no root, 24/7 via Termux:Boot โ your phone is an AI server |
-| ๐ฒ **PWA** | "Add to Home Screen" in browser | Fullscreen, offline page, service worker caching โ Android/iOS/Desktop |
-
-
-๐ฅ๏ธ Desktop App details
-
-
-๐ฑ Android (Termux) details
-
-
-๐ฒ PWA details
-
----
-
-## ๐ Bypass Geographic Blocks โ Use AI From Any Country
-
-> ๐ท๐บ ๐จ๐ณ ๐ฎ๐ท ๐จ๐บ ๐น๐ท **In Russia, China, Iran, or any blocked region?** OmniRoute's 3-level proxy system solves this completely.
-
-| Level | Badge | Configure In | Use Case |
-| ------------------ | ----- | ------------------ | ------------------------------- |
-| **Global** | ๐ข | Settings โ Proxy | All traffic through one proxy |
-| **Per-Provider** | ๐ก | Provider โ Proxy | Only specific providers proxied |
-| **Per-Connection** | ๐ต | Connection โ Proxy | Each API key uses its own proxy |
-
-**What gets proxied:** API requests โ
โข OAuth flows โ
โข Connection tests โ
โข Token refresh โ
โข Model sync โ
-
-**Protocols:** HTTP/HTTPS, SOCKS5 (`ENABLE_SOCKS5_PROXY=true`), Authenticated proxies
-
-### ๐ 1proxy โ Free Proxy Marketplace
-
-> Contributed by [@oyi77](https://github.com/oyi77) โ [#1847](https://github.com/diegosouzapw/OmniRoute/pull/1847)
-
-No proxy? Use the built-in **1proxy** integration for **hundreds of free, validated proxies** worldwide:
-
-- One-click sync (up to 500 proxies) โข Quality scores (0-100) โข Country filter โข Auto-rotation (quality/random/sequential) โข Auto-degradation โข Circuit breaker
-
-### Anti-Detection
-
-- ๐ **TLS Fingerprint Spoofing** โ browser-like TLS via `wreq-js`
-- ๐ **CLI Fingerprint Matching** โ matches native CLI binary signatures
-- ๐ **Proxy IP Preservation** โ stealth + IP masking simultaneously
-
-๐ **Full proxy documentation:** [`docs/PROXY_GUIDE.md`](docs/PROXY_GUIDE.md)
-
----
-
----
-
-## ๐ฐ Pricing at a Glance
-
-| Tier | Provider | Cost | Quota Reset | Best For |
-| ------------------- | --------------------------- | ------------------------- | ---------------- | --------------------------------- |
-| **๐ณ SUBSCRIPTION** | Claude Code (Pro) | $20/mo | 5h + weekly | Already subscribed |
-| | Codex (Plus/Pro) | $20-200/mo | 5h + weekly | OpenAI users |
-| | Gemini CLI | **FREE** | 180K/mo + 1K/day | Everyone! |
-| | GitHub Copilot | $10-19/mo | Monthly | GitHub users |
-| **๐ API KEY** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models |
-| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest |
-| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma |
-| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning |
-| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐ | None | Fastest + tool calling, ultralow |
-| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐ | None | Reasoning flagship from xAI |
-| | Mistral | Free trial + paid | Rate limited | European AI |
-| | OpenRouter | Pay-per-use | None | 100+ models aggr. |
-| | AgentRouter ๐ | Pay-per-use | None | $200 free credits at signup |
-| **๐ฐ CHEAP** | GLM-5 (via Z.AI) ๐ | $0.5/1M | Daily 10AM | 128K output, newest flagship |
-| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup |
-| | MiniMax M2.5 ๐ | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks |
-| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option |
-| | Kimi K2.5 (Moonshot API) ๐ | Pay-per-use | None | Direct Moonshot API access |
-| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost |
-| **๐ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited |
-| | Qwen | **$0** | Unlimited | 4 models unlimited |
-| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) |
-| | LongCat Flash-Lite ๐ | **$0** (50M tok/day ๐ฅ) | 1 RPS | Largest free quota on Earth |
-| | Pollinations AI ๐ | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 |
-| | Cloudflare Workers AI ๐ | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge |
-| | Scaleway AI ๐ | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B |
-
-> ๐ **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API.
-
-**๐ก See the full [$0 Free Stack (11 providers)](#-free-models--11-providers-0-forever) below.**
-
-> ๐ก **Understanding Dashboard Costs:**
->
-> The "cost" displayed in the Usage Analytics page is **for tracking and comparison purposes only**.
-> OmniRoute itself **never charges you anything** โ it's free, open-source software running on your machine.
-> If your dashboard shows "$290 total cost" while using free models, that's how much you **saved** compared to paid API pricing.
-> Think of it as a **savings tracker**, not a bill.
-
----
-
-## ๐ Free Models โ 11 Providers, $0 Forever
-
-> Combine all free providers into one unbreakable combo โ OmniRoute auto-routes between them when quota runs out.
-
-| Provider | Prefix | Free Models | Quota |
-| ----------------- | ----------- | ------------------------------------------------------------- | -------------------- |
-| **Kiro** | `kr/` | Claude Sonnet 4.5, Haiku 4.5, Opus 4.6 | 50 CREDITS per month |
-| **Qoder** | `if/` | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2.1 | โพ๏ธ Unlimited |
-| **Qwen** | `qw/` | qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next | โพ๏ธ Unlimited |
-| **Pollinations** | `pol/` | GPT-5, Claude, Gemini, DeepSeek, Llama 4, Mistral | No key needed |
-| **LongCat** | `lc/` | LongCat-Flash-Lite | 50M tokens/day ๐ฅ |
-| **Gemini CLI** | `gc/` | gemini-3-flash, gemini-2.5-pro | 180K tok/mo |
-| **Cloudflare AI** | `cf/` | 50+ models (Llama, Gemma, Mistral, Whisper) | 10K Neurons/day |
-| **Groq** | `groq/` | Llama 3.3 70B, Qwen3 32B, Kimi K2 | 14.4K RPD |
-| **NVIDIA NIM** | `nvidia/` | 129 models (DeepSeek, Llama, GLM, Kimi) | ~40 RPM |
-| **Cerebras** | `cerebras/` | Qwen3 235B, GPT-OSS 120B, Llama 3.1 | 1M tok/day |
-| **Scaleway** | `scw/` | Qwen3 235B, Llama 70B, DeepSeek V3 | 1M tokens (EU) |
-
-
-๐ 25+ more free providers โ Groq, Cerebras, Mistral, GitHub Models, OpenRouter, and more
-
-๐ **Complete free provider directory:** [`docs/FREE_TIERS.md`](docs/FREE_TIERS.md) โ 25+ providers, quotas, base URLs, model tables, and OmniRoute combo setup.
-
----
-
-## ๐๏ธ Free Transcription Combo
-
-> Transcribe any audio/video for **$0** โ Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup.
-
-| Provider | Free Credits | Best Model | Rate Limit |
-| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- |
-| ๐ข **Deepgram** | **$200 free** (signup) | `nova-3` โ best accuracy, 30+ languages | No RPM limit on free credits |
-| ๐ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ chapters, sentiment, PII | No RPM limit on free credits |
-| ๐ด **Groq** | **Free forever** | `whisper-large-v3` โ OpenAI Whisper | 30 RPM (rate limited) |
-
----
-
-**Suggested combo in `/dashboard/combos`:**
-
-```
-Name: free-transcription
-Strategy: Priority
-Nodes:
- [1] deepgram/nova-3 โ uses $200 free first
- [2] assemblyai/universal-3-pro โ fallback when Deepgram credits run out
- [3] groq/whisper-large-v3 โ free forever, emergency fallback
-```
-
-Then in `/dashboard/media` โ **Transcription** tab: upload any audio or video file โ select your combo endpoint โ get transcription in supported formats.
-
-## ๐ก Key Features
-
-> **4,690+ automated tests** across 517 test files. Not just a relay โ a full operational platform.
-
-| Feature | Why It Matters |
-| ---------------------------------------------------------------------------------------------------- | -------------------------------- |
-| ๐ง **Smart 4-Tier Fallback** โ Subscription โ API โ Cheap โ Free | Never stop coding, zero downtime |
-| ๐ **Format Translation** โ OpenAI โ Claude โ Gemini โ Responses API | Works with ANY CLI tool |
-| ๐๏ธ **Prompt Compression** โ 7 options including Caveman, RTK, and stacked pipelines | Save 15-95% eligible tokens |
-| ๐ค **MCP Server** โ 37 tools, 3 transports (stdio/SSE/HTTP), 10 scopes | IDE/agent tool integration |
-| ๐ก๏ธ **Resilience Engine** โ circuit breakers, cooldowns, TLS spoofing, anti-thundering herd | Auto-recovery from any failure |
-| ๐ต **10 Multi-Modal APIs** โ chat, embed, images, video, music, TTS, STT, moderation, rerank, search | One endpoint for everything |
-| ๐ **3-Level Proxy** โ global, per-provider, per-key + 1proxy free marketplace | Access AI from any country |
-| ๐ **Full Observability** โ unified logs, p50/p95/p99 telemetry, cost tracking, budget controls | Know exactly what's happening |
-
-
-๐ Complete feature list โ 30+ capabilities
-
----
-
-## ๐ฏ Use Cases โ Ready-Made Combo Playbooks
-
-### Case 0: "I want zero-config, auto-routing NOW"
-
-**Problem:** Don't want to create combos manually. Just want AI routing to work immediately.
+**Point any OpenAI-compatible client at OmniRoute:**
```bash
-# No combo creation needed! Use auto/ prefix directly:
-model: "auto" # Default LKGP routing across all connected providers
-model: "auto/coding" # Quality-first weights for code generation
-model: "auto/fast" # Low-latency routing (fastest provider first)
-model: "auto/cheap" # Cost-optimized (cheapest per token)
-model: "auto/offline" # High availability (most quota available)
-model: "auto/smart" # Best discovery (10% exploration rate)
+export OPENAI_BASE_URL=http://localhost:20128/v1
+export OPENAI_API_KEY=or_
```
-**How it works:**
-
-1. Add providers in Dashboard โ Providers (OAuth or API key)
-2. Use `auto/` prefix in any AI tool โ **no combo creation needed**
-3. OmniRoute dynamically builds a virtual combo from your active connections
-4. Routes using LKGP (Last Known Good Provider) + 6-factor scoring
-5. Session stickiness ensures consistent provider selection
-
-**Dashboard indicator:** A blue banner at the top shows "Auto-Routing Active" with a link to `/dashboard/combos` for configuration.
-
-**Monthly cost:** $0 (uses your existing free providers) or whatever your connected providers cost
+That's it. Cursor, Cline, Codex, Continue, Aider, and any SDK now work. โ Detailed setup: [`docs/SETUP_GUIDE.md`](docs/SETUP_GUIDE.md)
---
-### Case 1: "I have a Claude Pro subscription"
+## ๐ What's new in v3.8.0
-**Problem:** Quota expires unused, rate limits during heavy coding sessions.
+- ๐ค **Auto-Combo zero-config routing** โ just use `auto/coding`, `auto/cheap`, `auto/fast`, `auto/offline`, `auto/smart`, `auto/lkgp` as model IDs
+- ๐ฏ **Manifest-aware tier routing W1-W4** โ automatic tier prioritization
+- ๐ **Command Code provider** + **Z.AI quota labels** + **KIE video expansion**
+- ๐ **Windsurf + Devin CLI + GitLab Duo OAuth** flows
+- ๐ **9 new free providers**: LLM7, Lepton, Kluster, UncloseAI, BazaarLink, Completions, Enally, FreeTheAi, AgentRouter ($200 credits)
+- ๐ฉบ **Model Cooldowns dashboard** with manual re-enable
+- ๐จ **Cursor full OpenAI parity** (tools, streaming, sessions)
+- ๐ **Per-session sticky routing** for Codex
+- ๐ **Inworld TTS** enhancements
+- ๐ง **Reasoning Replay Cache** โ fixes 400s on DeepSeek V4, Kimi K2, Qwen-Thinking, GLM
+- ๐ **Reset-aware routing** strategy (14th strategy)
+- ๐ ๏ธ **20+ new CLI commands** (`omniroute setup/doctor/providers/combos`)
-```
-Combo: "maximize-claude"
- 1. cc/claude-opus-4-7 (use subscription fully)
- 2. glm/glm-5.1 (cheap backup when quota out โ $0.5/1M)
- 3. kr/claude-sonnet-4.5 (free emergency fallback via Kiro)
-
-Compression: standard (caveman) โ saves 30% tokens = stretch quota further
-Monthly cost: $20 (subscription) + ~$3 (backup) = $23 total
-vs. $20 + hitting limits + lost productivity = frustration
-```
-
-### Case 2: "I want $0 forever"
-
-**Problem:** Can't afford subscriptions, need reliable AI for coding.
-
-```
-Combo: "free-forever"
- 1. kr/claude-sonnet-4.5 (Claude 4.5 free unlimited via Kiro)
- 2. if/kimi-k2-thinking (reasoning model free via Qoder)
- 3. pol/gpt-5 (GPT-5 free via Pollinations โ no key)
- 4. lc/longcat-flash-lite (50M tokens/day free backup)
-
-Compression: aggressive โ saves 50% tokens = double your free quota
-Monthly cost: $0
-Quality: Production-ready models + 50% token savings
-```
-
-### Case 3: "I need 24/7 coding, no interruptions"
-
-**Problem:** Deadlines, can't afford any downtime.
-
-```
-Combo: "always-on"
- 1. cc/claude-opus-4-7 (best quality โ subscription)
- 2. cx/gpt-5.5 (second subscription โ OpenAI)
- 3. glm/glm-5.1 (cheap, resets daily โ $0.5/1M)
- 4. minimax/MiniMax-M2.5 (cheapest paid โ $0.3/1M)
- 5. kr/claude-sonnet-4.5 (free unlimited โ never fails)
-
-Compression: lite โ saves 15% tokens passively, zero risk
-Result: 5 layers of fallback = zero downtime
-Monthly cost: $20-200 (subscriptions) + $5-10 (backup)
-```
-
-### Case 4: "I'm in a blocked region (Russia, China, Iran...)"
-
-**Problem:** AI providers block my country, VPNs are slow.
-
-```
-Combo: "unblocked-ai"
- 1. kr/claude-sonnet-4.5 (free via Kiro + proxy)
- 2. pol/deepseek-r1 (Pollinations โ no geo-block)
- 3. groq/llama-3.3-70b (Groq + proxy)
-
-Proxy: Global proxy set in Settings โ or per-provider proxy override
-Result: Access ALL providers from ANY country
-Monthly cost: $0 (free providers) + $0 (1proxy free marketplace)
-```
-
-### Case 5: "I want maximum token savings"
-
-**Problem:** Token costs are eating my budget, need to squeeze every token.
-
-```
-Combo: "ultra-saver"
- 1. cc/claude-opus-4-7 (subscription โ best quality)
- 2. glm/glm-5.1 (cheap backup)
-
-Compression: ultra โ saves 75% tokens
-Result: 10K token prompt โ 2.5K tokens sent
-Montly savings: ~$150-300/month in token costs for heavy users
-```
-
-## ๐งช Evaluations (Evals)
-
-OmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ Evals** in the dashboard.
-
-### Built-in Golden Set
-
-The pre-loaded "OmniRoute Golden Set" contains test cases for:
-
-- Greetings, math, geography, code generation
-- JSON format compliance, translation, markdown generation
-- Safety refusal (harmful content), counting, boolean logic
-
-### Evaluation Strategies
-
-| Strategy | Description | Example |
-| ---------- | ------------------------------------------------ | -------------------------------- |
-| `exact` | Output must match exactly | `"4"` |
-| `contains` | Output must contain substring (case-insensitive) | `"Paris"` |
-| `regex` | Output must match regex pattern | `"1.*2.*3"` |
-| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` |
+โ Full changelog: [`CHANGELOG.md`](CHANGELOG.md)
---
-## ๐ Setup Guide
+## ๐ฏ Why OmniRoute Wins
-### Connect Your Coding Tool
+| | OmniRoute v3.8 | LiteLLM | OpenRouter |
+| ------------------ | ------------------- | ---------------- | ------------- |
+| Providers | **177+** | ~50 | ~50 |
+| Free providers | **11** | 0 | 0 |
+| OAuth providers | **14** | 0 | 1 |
+| Routing strategies | **14** | 3 | 1 |
+| Auto routing | โ
9-factor scoring | โ | โ |
+| Prompt compression | โ
RTK + Caveman | โ | โ |
+| MCP server | โ
37 tools | โ | โ |
+| A2A protocol | โ
v0.3 + 5 skills | โ | โ |
+| Desktop app | โ
Electron 41 | โ | โ |
+| PWA | โ
| โ | โ |
+| Self-hosted | โ
MIT | Limited | โ (cloud) |
+| Pricing | **$0 forever** | OSS / Cloud paid | 10% fee + API |
-Point any OpenAI-compatible tool to OmniRoute:
+โ Detailed comparison: [`docs/FEATURES.md`](docs/FEATURES.md)
-```txt
-Base URL: http://localhost:20128/v1
-API Key: [from Dashboard โ Endpoints]
-```
+---
-| Tool | Config Location |
-| --------------- | ----------------------------------------------------------------------------------------- |
-| **Claude Code** | `claude mcp add-server omniroute --type http --url http://localhost:20128/api/mcp/stream` |
-| **Codex CLI** | `OPENAI_BASE_URL=http://localhost:20128/v1 OPENAI_API_KEY=your-key codex` |
-| **Cursor** | Settings โ Models โ Add Model โ Override Base URL |
-| **Cline** | Extension settings โ Custom API Base URL |
-| **OpenClaw** | `OPENAI_BASE_URL=http://localhost:20128/v1 openclaw` |
-| **Gemini CLI** | Uses native OAuth via OmniRoute โ connect in Providers |
+## ๐ ๏ธ Compatible CLI Tools (17+)
-### Protocols (MCP + A2A)
+All work out-of-the-box once you point `OPENAI_BASE_URL` at OmniRoute:
+
+**Claude family:** Claude Code ยท Cline ยท Continue ยท Kilo Code ยท Kimi Coding
+**OpenAI family:** Codex CLI ยท Cursor ยท Aider ยท OpenClaw ยท Droid ยท AMP
+**Google family:** Gemini CLI ยท Antigravity ยท Jules
+**Others:** Windsurf ยท GitLab Duo ยท Devin CLI ยท Hermes ยท Amazon Q ยท Kiro ยท Qoder ยท Custom
+
+โ Full setup: [`docs/CLI-TOOLS.md`](docs/CLI-TOOLS.md)
+
+---
+
+## ๐ Providers (177+)
+
+### ๐ Free providers (11 โ no API key or unlimited tier)
+
+| Provider | Highlight |
+| --------------------------------------------------- | --------------------------------------- |
+| **Kiro AI** | 50 credits/month (Claude Sonnet/Haiku) |
+| **Qoder AI** | Unlimited (Kimi-K2, Qwen3, DeepSeek-R1) |
+| **Gemini CLI** | 180K tokens/month |
+| **Amazon Q** | AWS Builder ID OAuth |
+| **LongCat** | 50M tokens/day |
+| **Pollinations** | No API key, GPT-5 + Claude |
+| **AgentRouter** | $200 free credits |
+| **LLM7** ยท **Lepton** ยท **Kluster** ยท **UncloseAI** | New v3.8 free tiers |
+
+โ ๏ธ Qwen Code OAuth was **discontinued on 2026-04-15** (use API key with `alicode` provider instead).
+
+โ Curated guide: [`docs/FREE_TIERS.md`](docs/FREE_TIERS.md) ยท Full catalog: [`docs/PROVIDER_REFERENCE.md`](docs/PROVIDER_REFERENCE.md) (auto-generated)
+
+### ๐ OAuth providers (14)
+
+Claude Code ยท Codex ยท GitHub Copilot ยท Cursor ยท Antigravity ยท Gemini ยท Kimi Coding ยท Kilo Code ยท Cline ยท Qwen ยท Kiro ยท Qoder ยท Windsurf ยท GitLab Duo
+
+### ๐ API key providers (~123)
+
+OpenAI ยท Anthropic ยท Google ยท Mistral ยท Cohere ยท DeepSeek ยท Groq ยท Together ยท Fireworks ยท Cerebras ยท SambaNova ยท NVIDIA NIM ยท Bedrock ยท Vertex ยท Azure ยท Cloudflare AI ยท 100+ more.
+
+### ๐ Self-hosted (10)
+
+Ollama ยท LM Studio ยท vLLM ยท Llamafile ยท Lemonade ยท Petals ยท Triton ยท Docker Model Runner ยท Xinference ยท Oobabooga
+
+---
+
+## ๐ค Auto-Combo โ Zero-Config Routing
+
+Just use `auto/` as model ID. No combo setup needed.
```bash
-# MCP (stdio transport)
-omniroute --mcp
-
-# A2A (JSON-RPC 2.0)
-curl http://localhost:20128/.well-known/agent.json
+# 6 variants + plain `auto`:
+auto/coding # โ optimized for coding tasks
+auto/cheap # โ minimize cost
+auto/fast # โ minimize latency
+auto/offline # โ prefer local providers
+auto/smart # โ prefer top-tier models
+auto/lkgp # โ Last-Known-Good-Path (sticky)
+auto # โ balanced default
```
-### Key Environment Variables
+**How it picks:** 9-factor scoring (health ยท quota ยท cost ยท latency ยท taskFit ยท stability ยท tierPriority ยท tierAffinity ยท specificityMatch) over a virtual candidate pool built from all enabled providers.
-| Variable | Default | Purpose |
-| -------------------- | -------------- | ----------------------------------------- |
-| `PORT` | `20128` | API and dashboard port |
-| `DASHBOARD_PORT` | โ | Separate dashboard port (split-port mode) |
-| `REQUIRE_API_KEY` | `false` | Require API key for all requests |
-| `DATA_DIR` | `~/.omniroute` | Database and config storage |
-| `REQUEST_TIMEOUT_MS` | `600000` | Upstream response timeout |
-
-
-๐ Full Setup Guide โ All CLI tools, protocols, and environment variables
+โ Full guide: [`docs/AUTO-COMBO.md`](docs/AUTO-COMBO.md)
---
-## โ Frequently Asked Questions
+## ๐๏ธ Prompt Compression โ Save 15-95% Tokens
-
-๐ Why does my dashboard show high costs if I'm using free models?
-
-
-๐ณ Will I be charged by OmniRoute?
-
-
-๐ Are FREE providers really unlimited?
-
-
-๐ฐ How do I minimize my actual AI costs?
-
-
-๐๏ธ Will compression affect response quality?
-
-
-๐ Does OmniRoute work in countries where AI is blocked?
+โ [`docs/COMPRESSION_GUIDE.md`](docs/COMPRESSION_GUIDE.md) ยท [`docs/RTK_COMPRESSION.md`](docs/RTK_COMPRESSION.md) ยท [`docs/COMPRESSION_LANGUAGE_PACKS.md`](docs/COMPRESSION_LANGUAGE_PACKS.md)
---
-## ๐ Troubleshooting
+## ๐ Bypass Geographic Blocks
-| Problem | Quick Fix |
-| --------------------------------------------- | ------------------------------------------------------------------------------------ |
-| **"Language model did not provide messages"** | Provider quota exhausted โ check quota tracker, use combo fallback |
-| **Rate limiting (429)** | Add fallback combo: `cc/claude โ glm/glm-4.7 โ if/kimi-k2-thinking` |
-| **OAuth token expired** | Auto-refreshed by OmniRoute. If stuck: delete + re-auth in Providers |
-| **`unsupported_country_region_territory`** | Configure proxy in Settings โ Proxy (see [Proxy Guide](docs/PROXY_GUIDE.md)) |
-| **Docker SQLite locks** | Use `--stop-timeout 40` for clean WAL checkpoint on shutdown |
-| **Node.js runtime errors** | Use Node.js `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25` (24 LTS recommended) |
-| **`system-info` for bug reports** | Run `npm run system-info` and attach `system-info.txt` to your issue |
+For users in **Russia, China, Iran, Cuba, Turkey** and other regions:
-๐ **Full troubleshooting guide:** [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md)
+- **4-level outbound proxy** โ account / provider / combo / global scopes
+- **1proxy free marketplace** โ auto-syncs working HTTP/SOCKS5 proxies
+- **Anti-detection** โ TLS fingerprinting (JA3/JA4), CCH headshakes, header sanitization
+- **Public tunnels** โ Cloudflare (Quick or Named), ngrok, Tailscale Funnel for OAuth callbacks
+
+โ [`docs/PROXY_GUIDE.md`](docs/PROXY_GUIDE.md) ยท [`docs/TUNNELS_GUIDE.md`](docs/TUNNELS_GUIDE.md) ยท [`docs/STEALTH_GUIDE.md`](docs/STEALTH_GUIDE.md)
---
-## ๐ Performance Benchmarks
+## ๐ฑ Multi-Platform
-> OmniRoute is optimized for speed with minimal overhead. Run your own benchmarks to validate performance on your hardware.
+| Platform | Install | Doc |
+| --------------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
+| **CLI / Server** | `npm install -g omniroute` | [`SETUP_GUIDE.md`](docs/SETUP_GUIDE.md) |
+| **Desktop (Win/Mac/Linux)** | Electron installer from GitHub Releases | [`ELECTRON_GUIDE.md`](docs/ELECTRON_GUIDE.md) |
+| **PWA** | Install from any modern browser | [`PWA_GUIDE.md`](docs/PWA_GUIDE.md) |
+| **Android (Termux)** | `pkg install nodejs-lts && npm i -g omniroute` | [`TERMUX_GUIDE.md`](docs/TERMUX_GUIDE.md) |
+| **Docker** | `docker compose up` (base/cli/host/cliproxyapi profiles) | [`DOCKER_GUIDE.md`](docs/DOCKER_GUIDE.md) |
+| **VM / VPS** | Generic Ubuntu/Debian + nginx + systemd | [`VM_DEPLOYMENT_GUIDE.md`](docs/VM_DEPLOYMENT_GUIDE.md) |
+| **Fly.io** | `fly deploy` | [`FLY_IO_DEPLOYMENT_GUIDE.md`](docs/FLY_IO_DEPLOYMENT_GUIDE.md) |
-### Benchmark Your Instance
+---
-```bash
-# Install load testing tool
-npm install -g autocannon
+## ๐งฉ Extensibility
-# Test local OmniRoute instance
-autocannon -c 10 -d 30 -m POST \
- -H "Authorization: Bearer your-api-key" \
- -H "Content-Type: application/json" \
- -b '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}' \
- http://localhost:20128/v1/chat/completions
+| System | What it does | Docs |
+| ----------------------- | ----------------------------------------------------------------------- | -------------------------------------------- |
+| ๐ง **Skills** | Built-in skills + marketplace + sandboxed custom skills (Docker) | [`docs/SKILLS.md`](docs/SKILLS.md) |
+| ๐พ **Memory** | Persistent conversational memory (SQLite FTS5 + Qdrant vector) | [`docs/MEMORY.md`](docs/MEMORY.md) |
+| โ๏ธ **Cloud Agents** | Submit long tasks to Codex Cloud / Devin / Jules | [`docs/CLOUD_AGENT.md`](docs/CLOUD_AGENT.md) |
+| ๐ช **Webhooks** | HMAC-signed event delivery (request.completed, quota.exceeded, etc.) | [`docs/WEBHOOKS.md`](docs/WEBHOOKS.md) |
+| ๐ก๏ธ **Guardrails** | PII masker, prompt injection guard, vision bridge โ hot-reload | [`docs/GUARDRAILS.md`](docs/GUARDRAILS.md) |
+| ๐งช **Evals** | Suite-based regression testing (combos/models/cases/rubrics) | [`docs/EVALS.md`](docs/EVALS.md) |
+| ๐ **Compliance/Audit** | `audit_log` table, retention, `noLog` opt-out, SSRF logging | [`docs/COMPLIANCE.md`](docs/COMPLIANCE.md) |
+| ๐ก๏ธ **MCP Server** | 37 tools, 3 transports (stdio/SSE/Streamable HTTP), ~13 scopes | [`docs/MCP-SERVER.md`](docs/MCP-SERVER.md) |
+| ๐ค **A2A Protocol** | v0.3 JSON-RPC, 5 skills (smart-routing, quota, discovery, cost, health) | [`docs/A2A-SERVER.md`](docs/A2A-SERVER.md) |
+
+---
+
+## ๐ Documentation
+
+Everything you need, organized by area.
+
+### ๐ Start here
+
+- [`SETUP_GUIDE.md`](docs/SETUP_GUIDE.md) โ install + connect first provider
+- [`USER_GUIDE.md`](docs/USER_GUIDE.md) โ end-user manual (modes, combos, CLIs, audio, ~1200 lines)
+- [`FREE_TIERS.md`](docs/FREE_TIERS.md) โ start free, no card
+- [`TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) โ common issues + v3.8 known issues
+
+### ๐๏ธ Architecture
+
+- [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) โ high-level architecture
+- [`CODEBASE_DOCUMENTATION.md`](docs/CODEBASE_DOCUMENTATION.md) โ engineering reference
+- [`REPOSITORY_MAP.md`](docs/REPOSITORY_MAP.md) โ every directory and root file
+- [`FEATURES.md`](docs/FEATURES.md) โ full feature matrix
+
+### ๐ API & contracts
+
+- [`API_REFERENCE.md`](docs/API_REFERENCE.md) โ endpoint reference
+- [`openapi.yaml`](docs/openapi.yaml) โ OpenAPI 3.0 spec
+- [`PROVIDER_REFERENCE.md`](docs/PROVIDER_REFERENCE.md) โ full catalog (auto-generated)
+- [`CLI-TOOLS.md`](docs/CLI-TOOLS.md) โ CLI integrations + internal CLI
+- [`ENVIRONMENT.md`](docs/ENVIRONMENT.md) โ all env vars
+
+### ๐ฏ Routing & resilience
+
+- [`AUTO-COMBO.md`](docs/AUTO-COMBO.md) โ Auto-Combo (9-factor scoring, 14 strategies)
+- [`RESILIENCE_GUIDE.md`](docs/RESILIENCE_GUIDE.md) โ circuit breaker + cooldown + lockout
+- [`REASONING_REPLAY.md`](docs/REASONING_REPLAY.md) โ reasoning cache for DeepSeek/Kimi/Qwen
+- [`STEALTH_GUIDE.md`](docs/STEALTH_GUIDE.md) โ TLS fingerprinting + obfuscation
+
+### ๐ค Agent protocols
+
+- [`AGENT_PROTOCOLS_GUIDE.md`](docs/AGENT_PROTOCOLS_GUIDE.md) โ A2A vs ACP vs Cloud Agents
+- [`MCP-SERVER.md`](docs/MCP-SERVER.md) โ Model Context Protocol server
+- [`A2A-SERVER.md`](docs/A2A-SERVER.md) โ Agent-to-Agent protocol
+- [`CLOUD_AGENT.md`](docs/CLOUD_AGENT.md) โ Codex Cloud / Devin / Jules
+
+### ๐ง Extensions
+
+- [`SKILLS.md`](docs/SKILLS.md) โ Skills framework
+- [`MEMORY.md`](docs/MEMORY.md) โ Memory system
+- [`EVALS.md`](docs/EVALS.md) โ Eval framework
+- [`GUARDRAILS.md`](docs/GUARDRAILS.md) โ PII / injection / vision
+- [`WEBHOOKS.md`](docs/WEBHOOKS.md) โ Webhook delivery
+- [`COMPLIANCE.md`](docs/COMPLIANCE.md) โ Audit + retention
+- [`AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md) โ Authorization pipeline
+
+### ๐๏ธ Compression
+
+- [`COMPRESSION_GUIDE.md`](docs/COMPRESSION_GUIDE.md)
+- [`COMPRESSION_ENGINES.md`](docs/COMPRESSION_ENGINES.md)
+- [`COMPRESSION_RULES_FORMAT.md`](docs/COMPRESSION_RULES_FORMAT.md)
+- [`COMPRESSION_LANGUAGE_PACKS.md`](docs/COMPRESSION_LANGUAGE_PACKS.md)
+- [`RTK_COMPRESSION.md`](docs/RTK_COMPRESSION.md)
+
+### ๐ Deployment
+
+- [`DOCKER_GUIDE.md`](docs/DOCKER_GUIDE.md)
+- [`VM_DEPLOYMENT_GUIDE.md`](docs/VM_DEPLOYMENT_GUIDE.md)
+- [`FLY_IO_DEPLOYMENT_GUIDE.md`](docs/FLY_IO_DEPLOYMENT_GUIDE.md)
+- [`ELECTRON_GUIDE.md`](docs/ELECTRON_GUIDE.md)
+- [`PWA_GUIDE.md`](docs/PWA_GUIDE.md)
+- [`TERMUX_GUIDE.md`](docs/TERMUX_GUIDE.md)
+- [`TUNNELS_GUIDE.md`](docs/TUNNELS_GUIDE.md)
+- [`PROXY_GUIDE.md`](docs/PROXY_GUIDE.md)
+
+### ๐ Operations
+
+- [`RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) โ release flow with Claude Code skills
+- [`COVERAGE_PLAN.md`](docs/COVERAGE_PLAN.md) โ test coverage state (current: 82.58%/82.58%/84.23%/75.22%)
+- [`I18N.md`](docs/I18N.md) โ 30 supported locales
+- [`UNINSTALL.md`](docs/UNINSTALL.md)
+
+### ๐ค Contributing & policy
+
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) โ contributor guide
+- [`SECURITY.md`](SECURITY.md) โ security policy
+- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
+- [`CLAUDE.md`](CLAUDE.md) โ rules for Claude Code agents
+- [`AGENTS.md`](AGENTS.md) โ rules for non-Claude agents
+- [`GEMINI.md`](GEMINI.md) โ rules for Gemini agents
+
+---
+
+## ๐ก Use Cases
+
+| Scenario | Solution |
+| --------------------------------- | ------------------------------------------------------------- |
+| "Claude Pro user, hit rate limit" | Combo: Claude โ GLM โ DeepSeek (auto-fallback) |
+| "Want $0 forever" | `auto/cheap` โ Kiro/Qoder/Pollinations fallback chain |
+| "24/7 coding, no interruptions" | `auto/lkgp` (sticky to last-good) + Resilience |
+| "Blocked region" | 1proxy free marketplace + Cloudflare Quick Tunnel |
+| "Max token savings" | Stacked compression: `rtk โ caveman` (78-95% on logs) |
+| "Multi-agent system" | Expose OmniRoute as A2A node, route via `smart-routing` skill |
+| "Long-running coding task" | Cloud Agents โ Devin/Jules with management auth |
+
+โ Detailed playbooks: [`USER_GUIDE.md`](docs/USER_GUIDE.md) ยท [`AUTO-COMBO.md`](docs/AUTO-COMBO.md)
+
+---
+
+## ๐ก Protocols supported
+
+OmniRoute speaks all major AI protocols โ clients don't need to change:
+
+- **OpenAI** (Chat Completions, Responses, Embeddings, Images, Audio, Files, Batches, Rerank, Moderations)
+- **Anthropic Messages** (Claude format, with thinking blocks + reasoning replay)
+- **Google Gemini** (generateContent + Vertex)
+- **Claude Code** (CLI-specific format with CCH + fingerprinting)
+- **Cursor** (proprietary format with tool calls)
+- **Kiro** (AWS Builder ID OAuth)
+- **MCP** (Model Context Protocol โ 37 tools, stdio/SSE/Streamable HTTP)
+- **A2A** (Agent-to-Agent v0.3 JSON-RPC โ agent card at `/.well-known/agent.json`)
+
+---
+
+## ๐๏ธ Architecture (10-second tour)
+
+```
+Client โ /v1/chat/completions โ [CORS โ Zod โ Auth โ Authz โ Guardrails]
+ โ handleChatCore() โ [Cache โ Rate limit โ Combo routing]
+ โ translateRequest โ getExecutor โ fetch upstream (with retry)
+ โ response translation โ SSE stream or JSON
+ โ [Compliance audit] โ response
```
-### Expected Performance
+**Major pieces:**
-| Metric | OmniRoute | LiteLLM | Bifrost (claimed) |
-| -------------------- | --------- | ------- | ----------------- |
-| **RPS (sustained)** | ~5,000+ | ~3,000 | ~13,925 |
-| **Latency overhead** | <5ms | <10ms | <100ยตs |
-| **Memory (idle)** | ~150MB | ~200MB | 32MB |
-| **Cold start** | <2s | <5s | <1s |
+- **`src/app/`** โ Next.js 16 App Router (60+ API routes + 30 dashboard pages)
+- **`src/lib/`** โ 50+ domain modules (db, a2a, memory, skills, guardrails, evals, โฆ)
+- **`open-sse/`** โ Streaming engine workspace (31 executors, 9+8+9 translators, 80+ services, 37-tool MCP server)
+- **`src/domain/`** โ Pure business logic (policies, fallback, cost rules)
+- **`src/server/`** โ Server-only (authz pipeline, cors)
-### What Impacts Performance
-
-- **Prompt compression** โ RTK/Caveman adds ~1-3ms latency but saves 15-95% tokens
-- **Format translation** โ OpenAI โ Claude adds ~2-5ms for format conversion
-- **Proxy overhead** โ Global proxy adds ~10-50ms depending on proxy location
-- **Caching** โ Semantic cache hit avoids upstream entirely (0ms added)
-
-### Optimization Tips
-
-1. **Enable compression** โ Lite/Standard mode adds minimal latency for significant savings
-2. **Use local providers** โ Same-region providers have lowest latency
-3. **Configure circuit breakers** โ Prevent cascading failures during high load
-4. **Enable semantic cache** โ Repeated queries hit cache without upstream call
-
-๐ **Full performance guide:** [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md)
+โ Deep dive: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) ยท [`docs/CODEBASE_DOCUMENTATION.md`](docs/CODEBASE_DOCUMENTATION.md)
---
-## ๐ Competitive Comparison
+## ๐ i18n
-> OmniRoute vs other AI Gateways โ See why developers choose OmniRoute
+UI translated to **30 languages** with full RTL support for Arabic and Hebrew.
-### Feature Comparison
+๐ [English](README.md) ยท [Portuguรชs](docs/i18n/pt-BR/README.md) ยท [Espaรฑol](docs/i18n/es/README.md) ยท [Franรงais](docs/i18n/fr/README.md) ยท [Deutsch](docs/i18n/de/README.md) ยท [ไธญๆ](docs/i18n/zh-CN/README.md) ยท [ๆฅๆฌ่ช](docs/i18n/ja/README.md) ยท [ํ๊ตญ์ด](docs/i18n/ko/README.md) ยท [ุงูุนุฑุจูุฉ](docs/i18n/ar/README.md) ยท [เคนเคฟเคจเฅเคฆเฅ](docs/i18n/hi/README.md) ยท [ะ ัััะบะธะน](docs/i18n/ru/README.md) ยท [+ 19 more](docs/i18n/)
-| Feature | OmniRoute | LiteLLM | Bifrost | Routerly |
-| ------------------ | :--------------: | :-----: | :-----: | :------: |
-| **Providers** | **160+** | 100+ | 15+ | 8 |
-| **Token Savings** | **15-95%** | โ | โ | โ |
-| **Free Tier** | **11 providers** | 1 | 0 | 0 |
-| **Auto-Combo** | **6-factor** | โ | โ | basic |
-| **MCP Server** | **37 tools** | โ | โ
| โ |
-| **A2A Protocol** | **โ
** | โ | โ | โ |
-| **Desktop App** | **โ
** | โ | โ | โ |
-| **Memory/Skills** | **โ
** | โ | โ | โ |
-| **i18n Languages** | **40+** | โ | โ | โ |
-| **Price** | **Free** | $0 | $19/mo | $9.99/mo |
-
-### What Makes OmniRoute Unique
-
-#### ๐๏ธ **RTK+Caveman Compression** (Exclusive)
-
-No other gateway offers prompt compression. OmniRoute saves 15-95% tokens on eligible payloads using RTK (command-output) and Caveman (context condensation) engines.
-
-#### ๐ **11 Free Providers** (Exclusive)
-
-- Kiro AI โ Claude Sonnet/Haiku (50 credits/month)
-- Qoder AI โ Kimi-K2, Qwen3 unlimited
-- Pollinations โ GPT-5, no API key needed
-- LongCat โ 50M tokens/day
-- 7 more
-
-#### ๐ค **Auto-Combo 6-Factor Routing** (Superior)
-
-OmniRoute scores each request on 7 factors (health, quota, cost, latency, capability, stability, tier) โ smarter than Routerly's basic LLM-based routing.
-
-#### ๐ง **MCP Server + A2A Protocol** (Exclusive)
-
-37 MCP tools for IDE integration and agent-to-agent communication. No other gateway offers both.
-
-#### ๐ฅ๏ธ **Desktop App** (Exclusive)
-
-Electron desktop app for Windows/macOS/Linux with system tray, auto-start, and offline mode.
+โ Adding a language: [`docs/I18N.md`](docs/I18N.md)
---
-## ๐ Free Forever โ No Credit Card Required
+## ๐ค Community
-> Use OmniRoute's free providers for $0 lifetime access to AI. No API key needed for some, others just sign up free.
-
-### Free Provider Directory
-
-| Provider | Models | Quota | Auth Required |
-| ----------------- | --------------------------------- | --------------- | -------------- |
-| **Kiro (AWS)** | Claude Sonnet/Haiku | Unlimited | OAuth |
-| **Qoder** | kimi-k2, qwen3-coder, deepseek-r1 | Unlimited | PAT token |
-| **Pollinations** | GPT-5, Claude, Llama 4 | No key needed | โ |
-| **Qwen Code** | qwen3-coder-plus | Unlimited | Device code |
-| **LongCat** | Flash-Lite | 50M tokens/day | API key (free) |
-| **Gemini CLI** | gemini-2.5-flash | 180K/mo | OAuth |
-| **Cloudflare AI** | 50+ models | 10K neurons/day | โ |
-| **Groq** | Llama 3.3 70B | 30 RPM | API key (free) |
-| **NVIDIA NIM** | 129 models | ~40 RPM | API key (free) |
-| **Cerebras** | Qwen3 235B | 1M tokens/day | API key (free) |
-| **Scaleway** | Qwen3 235B | 1M tokens | API key (free) |
-
-### Total Free Capacity
-
-- **~31,000+ requests/day** combined
-- **~32B+ tokens/month**
-- **500+ models**
-- **$0 forever**
-
-### Quick Start with Free Stack
-
-```bash
-# Point any tool to OmniRoute's free endpoint
-Base URL: http://localhost:20128/v1
-API Key: any-string
-Model: auto # Auto-Combo picks best free model
-```
-
-Or use the built-in **Free Stack** combo in `/dashboard/combos` โ round-robins all free providers automatically.
-
-๐ **Full free provider guide:** [`docs/FREE_TIERS.md`](docs/FREE_TIERS.md)
+- ๐ **Website:** [omniroute.online](https://omniroute.online)
+- ๐ฆ **npm:** [omniroute](https://www.npmjs.com/package/omniroute)
+- ๐ณ **Docker Hub:** [diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute)
+- ๐ฌ **WhatsApp (BR):** Brazilian community group โ see README link
+- ๐ **Issues:** [GitHub Issues](https://github.com/diegosouzapw/OmniRoute/issues)
+- ๐ก **Discussions:** [GitHub Discussions](https://github.com/diegosouzapw/OmniRoute/discussions)
---
-## ๐ ๏ธ Tech Stack
+## โค๏ธ Contributing
-
-Click to expand tech stack details
+**Adding a provider?** [`docs/ARCHITECTURE.md ยง Adding a New Provider`](docs/ARCHITECTURE.md)
+**Adding an MCP tool?** [`docs/MCP-SERVER.md`](docs/MCP-SERVER.md)
+**Adding an A2A skill?** [`docs/A2A-SERVER.md ยง Adding a New Skill`](docs/A2A-SERVER.md)
---
-## ๐ Documentation
+## ๐ Security
-### ๐ Getting Started
-
-| Document | Description |
-| ------------------------------------- | ----------------------------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment |
-| [Setup Guide](docs/SETUP_GUIDE.md) | Full install methods, CLI tool configs, protocol setup, timeout tuning |
-| [CLI Tools Guide](docs/CLI-TOOLS.md) | Per-tool setup for Claude Code, Codex, Cursor, Cline, OpenClaw, Kilo, Copilot |
-| [Quick Start](README.md#-quick-start) | 3-step install โ connect โ configure |
-
-### ๐ง Operations & Deployment
-
-| Document | Description |
-| ---------------------------------------------------- | -------------------------------------------------------------- |
-| [Docker Guide](docs/DOCKER_GUIDE.md) | Docker run, Compose profiles, Caddy HTTPS, tunnels, image tags |
-| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup |
-| [Fly.io Deployment](docs/FLY_IO_DEPLOYMENT_GUIDE.md) | Deploy to Fly.io with persistent storage |
-| [Termux Guide](docs/TERMUX_GUIDE.md) | Run OmniRoute on Android via Termux |
-| [PWA Guide](docs/PWA_GUIDE.md) | Progressive Web App install, caching, architecture |
-| [Uninstall Guide](docs/UNINSTALL.md) | Clean removal for all install methods |
-| [Environment Config](docs/ENVIRONMENT.md) | Complete `.env` variables and references |
-
-### ๐ง Features & Architecture
-
-| Document | Description |
-| ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [Architecture](docs/ARCHITECTURE.md) | System architecture, data flow, and internals |
-| [Compression Guide](docs/COMPRESSION_GUIDE.md) | 7-option pipeline: off / lite / standard / aggressive / ultra / RTK / stacked |
-| [RTK Compression](docs/RTK_COMPRESSION.md) | Command-output compression, filters, trust, verify, raw-output recovery |
-| [Compression Engines](docs/COMPRESSION_ENGINES.md) | Caveman, RTK, stacked pipelines, dashboard/API/MCP surfaces |
-| [Compression Rules Format](docs/COMPRESSION_RULES_FORMAT.md) | JSON rule-pack schemas for Caveman and RTK filters |
-| [Compression Language Packs](docs/COMPRESSION_LANGUAGE_PACKS.md) | Language detection and Caveman rule-pack authoring |
-| [Resilience Guide](docs/RESILIENCE_GUIDE.md) | Circuit breakers, cooldowns, queue, anti-thundering herd, TLS spoofing |
-| [Auto-Combo Engine](docs/AUTO-COMBO.md) | 6-factor scoring, mode packs, self-healing |
-| [Proxy Guide](docs/PROXY_GUIDE.md) | 3-level proxy system, 1proxy marketplace, registry CRUD |
-| [Free Tiers](docs/FREE_TIERS.md) | 25+ free API providers consolidated directory |
-| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots |
-| [Codebase Documentation](docs/CODEBASE_DOCUMENTATION.md) | Beginner-friendly codebase walkthrough |
-
-### ๐ค Protocols & APIs
-
-| Document | Description |
-| ------------------------------------------- | --------------------------------------------------- |
-| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples |
-| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification |
-| [MCP Server](open-sse/mcp-server/README.md) | 29 MCP tools, IDE configs, Python/TS/Go clients |
-| [MCP Server Guide](docs/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/A2A-SERVER.md) | A2A agent card, tasks, skills, and streaming |
-
-### ๐ Project & Quality
-
-| Document | Description |
-| ---------------------------------------------- | ----------------------------------------------- |
-| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
-| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices |
-| [i18n Guide](docs/I18N.md) | 40+ language support, translation workflow, RTL |
-| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps |
-| [Coverage Plan](docs/COVERAGE_PLAN.md) | Test coverage strategy and 4,690+ test suite |
-
----
-
-## โญ Top Contributors
-
-> OmniRoute is shaped by a passionate open-source community. These individuals have made exceptional contributions that directly impact the quality, stability, and reach of the project. **Thank you.**
-
-
-
-
-
- oyi77
- ๐ฅ 190 commits โข +72K lines Analytics engine, SQL aggregations,
-
-
-
- Chris Staley
- ๐ฅ 72 commits โข +5.7K lines SSE stream hardening, Responses API,
-
-
-
- zenobit
- ๐ฅ 62 commits โข +24K lines CI/CD pipeline, i18n for 33 languages,
-
-
-
- R.D. & Randi
- ๐
107 commits โข +28K lines Endpoints page, tunnel integrations,
-
-
-
- benzntech
- ๐
20 commits โข +7.5K lines Electron desktop app, auto-updater,
-
-
-
-
-> ๐ These contributors' features, bug fixes, and infrastructure improvements are a **core part** of what makes OmniRoute reliable and feature-rich. Every pull request, every test case, and every i18n translation file matters. Open source is built by people like them.
-
----
-
-## ๐ฅ Contributors
-
-[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)
-
-### How to Contribute
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-
-### Releasing a New Version
-
-```bash
-# Create a release โ npm publish happens automatically
-gh release create v2.0.0 --title "v2.0.0" --generate-notes
-```
-
----
-
-## ๐ Star History
-
-
-
-
-
-
-## ๐ StarMapper
-
-
-
-
-
-
-## ๐ Acknowledgments
-
-Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite.
-
-Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** by **[router-for-me](https://github.com/router-for-me)** โ the original Go implementation that inspired this JavaScript port.
-
-Special thanks to **[Caveman](https://github.com/JuliusBrussee/caveman)** by **[JuliusBrussee](https://github.com/JuliusBrussee)** (โญ 51K+) โ the viral "why use many token when few token do trick" project whose caveman-speak compression philosophy inspired OmniRoute's standard compression mode and 30+ filler/condensation regex rules.
-
-Special thanks to **[RTK - Rust Token Killer](https://github.com/rtk-ai/rtk)** by **[RTK AI](https://github.com/rtk-ai)** โ the high-performance command-output compression project whose terminal, build, test, git, and tool-output filtering model inspired OmniRoute's RTK engine, JSON filter DSL, raw-output recovery, and stacked RTK โ Caveman compression pipeline.
+- **Reporting:** see [`SECURITY.md`](SECURITY.md) for disclosure policy
+- **Supported versions:** 3.8.x (Active), 3.7.x (Security only)
+- **Secrets:** never commit. Use `.env` (auto-generated from `.env.example` on first install) or vaults
+- **Encryption:** credentials at rest with AES-256-GCM
+- **Authz:** route-aware classification (`src/server/authz/`) โ see [`docs/AUTHZ_GUIDE.md`](docs/AUTHZ_GUIDE.md)
+- **Guardrails:** PII masking, prompt injection detection โ hot-reloadable
---
## ๐ License
-MIT License - see [LICENSE](LICENSE) for details.
+[MIT](LICENSE) ยฉ 2025-2026 [Diego Souza](https://github.com/diegosouzapw)
+
+Free forever. Self-hosted. No tracking. No cloud lock-in.
---
-
Built with โค๏ธ for developers who code 24/7
-
-
omniroute.online
+
+**[โฌ Back to top](#-omniroute)** ยท Built with โค๏ธ for the open-source AI community.
+
+
OmniRoute v3.8.0 ยท Node โฅ20.20.2 ยท MIT License
+
.ts` | One module per domain: providers, combos, apiKeys, users, sessions, usage, audit*log, webhooks, skills, memory_entries, cloud_agent_tasks, evals*\*, reasoning_cache, etc. |
+
+### `src/domain/`
+
+| Module | Purpose |
+| ---------------------- | ----------------------------------------------------------------------- |
+| `policy.ts` | Policy engine |
+| `fallbackPolicy.ts` | Fallback decision tree |
+| `costRules.ts` | Cost calculation rules |
+| `lockoutPolicy.ts` | Model/connection lockout policy |
+| `tagRouter.ts` | Tag-based routing |
+| `comboResolver.ts` | Combo resolution (used by combo engine) |
+| `modelAvailability.ts` | Per-model availability check |
+| `assessment/` | Model assessment (Phase 1 of RFC-AUTO-ASSESSMENT โ see `docs/archive/`) |
+
+### `src/server/`
+
+| Module | Purpose |
+| -------- | --------------------------------------------------------------------------------------- |
+| `authz/` | Authorization pipeline: `classify` โ `policies` โ `enforce` โ see `docs/AUTHZ_GUIDE.md` |
+| `cors/` | CORS configuration |
+| `auth/` | Session middleware |
+
+### `src/shared/`
+
+| Module | Purpose |
+| -------------------------------- | ------------------------------------------------------------- |
+| `constants/providers.ts` | **177 providers** with Zod validation (source of truth) |
+| `constants/cliTools.ts` | External CLI tool registry |
+| `constants/routingStrategies.ts` | **14 routing strategies** with priorities |
+| `constants/publicApiRoutes.ts` | Routes that require Bearer (vs management) auth |
+| `constants/upstreamHeaders.ts` | Header denylist for upstream requests |
+| `validation/schemas.ts` | ~80 Zod schemas (single source of truth for API contracts) |
+| `validation/helpers.ts` | Zod validation helpers (`validateBody`, etc.) |
+| `types/` | Shared TS types |
+| `contracts/` | Public API contracts (consumed by `files:` in `package.json`) |
+| `utils/circuitBreaker.ts` | Provider circuit breaker (see `docs/RESILIENCE_GUIDE.md`) |
+| `utils/apiAuth.ts` | API key validation, scope checking |
+| `utils/fetchTimeout.ts` | Timeout/abort wrappers for upstream fetch |
+
+---
+
+## `open-sse/` โ Streaming Engine Workspace
+
+Separate npm workspace (`@omniroute/open-sse`). Handles request processing + provider execution.
+
+```
+open-sse/
+โโโ handlers/ # 15 files (11 handlers + 4 helpers): chatCore, responsesHandler, embeddings, audio, image, video, music, rerank, moderations, search, etc.
+โโโ executors/ # 31 provider-specific executors (extend BaseExecutor)
+โโโ translator/ # Format converters (9 request, 8 response, 9 helpers)
+โโโ transformer/ # Responses API โ Chat Completions (TransformStream)
+โโโ services/ # ~80+ service modules (combo, accountFallback, autoCombo, reasoningCache, claude code/chatgpt stealth, modelDeprecation, taskAwareRouter, workflowFSM, etc.)
+โโโ mcp-server/ # MCP server (37 tools, 3 transports, ~13 scopes)
+โโโ config/ # Provider/model registries, header config, model aliases
+โโโ utils/ # TLS client, proxy fetch/dispatcher, network helpers
+โโโ index.ts # Workspace entry
+โโโ package.json # Workspace manifest
+โโโ tsconfig.json # Workspace TS config
+โโโ types.d.ts # Workspace type declarations
+```
+
+### `open-sse/mcp-server/`
+
+| Path | Purpose |
+| --------------------------- | -------------------------------------------------------------------- |
+| `server.ts` | MCP server lifecycle (stdio + HTTP transports) |
+| `httpTransport.ts` | HTTP Streamable + SSE transports (`/api/mcp/sse`, `/api/mcp/stream`) |
+| `audit.ts` | Audit logging to `mcp_tool_audit` table |
+| `scopeEnforcement.ts` | Per-tool scope validation |
+| `runtimeHeartbeat.ts` | Health heartbeat to `DATA_DIR/runtime/mcp-heartbeat.json` |
+| `descriptionCompressor.ts` | Compress tool description metadata to save context |
+| `schemas/tools.ts` | 30 base tool definitions + scopes |
+| `tools/advancedTools.ts` | Advanced tool implementations |
+| `tools/memoryTools.ts` | 3 memory tools (search/add/clear) |
+| `tools/skillTools.ts` | 4 skill tools (list/enable/execute/executions) |
+| `tools/compressionTools.ts` | 5 compression tools |
+| `README.md` | Internal MCP server README (cross-linked from `docs/MCP-SERVER.md`) |
+
+---
+
+## `electron/` โ Desktop Wrapper
+
+| File | Purpose |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `main.js` | Electron main process (BrowserWindow, embedded Next.js server, tray, auto-update) |
+| `preload.js` | IPC bridge (contextBridge โ `window.omniroute`) |
+| `package.json` | electron-builder config + Electron 41 + electron-builder 26.10 deps |
+| `assets/` | App icons (Windows .ico, macOS .icns, Linux .png) |
+| `dist-electron/` | Build output (gitignored) |
+| `types.d.ts` | Type declarations for renderer bridge |
+| `README.md` | Internal Electron README (see also `docs/ELECTRON_GUIDE.md`) |
+
+---
+
+## `bin/` โ CLI
+
+| File | Purpose |
+| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `omniroute.mjs` | Main CLI entry โ `omniroute serve`, `omniroute setup`, `omniroute doctor`, `omniroute providers`, `omniroute combos`, etc. |
+| `reset-password.mjs` | Standalone password reset CLI |
+| `cli/commands/setup.mjs` | Interactive + non-interactive setup wizard |
+| `cli/commands/doctor.mjs` | System health diagnostics (8+ checks) |
+| `cli/commands/providers.mjs` | Provider list/test/validate |
+| `cli/{args,data-dir,encryption,io,provider-catalog,provider-store,provider-test,settings-store,sqlite}.mjs` | CLI helper modules |
+| `nodeRuntimeSupport.mjs` | Validate supported Node.js version on install |
+
+---
+
+## `scripts/` โ Build & Check Scripts
+
+| Script | Purpose |
+| ----------------------------------- | -------------------------------------------------------------------------- |
+| `run-next.mjs` | Dev/start runner with env hydration |
+| `build-next-isolated.mjs` | Standalone build (Next.js 16 standalone) |
+| `prepublish.ts` | Package preparation before `npm pack` |
+| `postinstall.mjs` | Auto-create `.env` from `.env.example` on first install |
+| `sync-env.mjs` | Re-sync `.env` keys with `.env.example` |
+| `check-cycles.mjs` | Detect circular dependencies |
+| `check-route-validation.mjs` | Validate all API routes have Zod validation |
+| `check-t11-any-budget.mjs` | Enforce explicit `any` budget per file |
+| `check-docs-sync.mjs` | Validate docs version sync (existing pre-commit) |
+| **`check-env-doc-sync.mjs`** | NEW: cross-check env vars in code vs `.env.example` vs `ENVIRONMENT.md` |
+| **`check-docs-counts-sync.mjs`** | NEW: validate counts (executors, strategies, OAuth, A2A skills) match docs |
+| **`check-deprecated-versions.mjs`** | NEW: flag stale versions/dates in docs |
+| `check-supported-node-runtime.ts` | Validate current Node version is supported |
+| `check-pr-test-policy.mjs` | Enforce "tests required" rule on production code changes |
+| **`gen-provider-reference.ts`** | NEW: auto-generate `docs/PROVIDER_REFERENCE.md` from catalog |
+| `generate-docs-index.mjs` | Build `src/app/docs/lib/docs-auto-generated.ts` from `docs/*.md` |
+| `i18n/generate-multilang.mjs` | Translate UI strings + docs via Google Translate |
+| `i18n_autotranslate.py` | LLM-based doc translation pipeline |
+| `validate_translation.py` | Per-locale translation validation |
+| `check_translations.py` | Code-side i18n key check |
+| `run-playwright-tests.mjs` | Playwright E2E runner |
+| `run-protocol-clients-tests.mjs` | MCP/A2A E2E runner |
+| `run-ecosystem-tests.mjs` | Ecosystem (provider integration) tests |
+| `test-report-summary.mjs` | Generate coverage summary markdown |
+| `smoke-electron-packaged.mjs` | Smoke-test packaged Electron build |
+| `native-binary-compat.mjs` | Validate native deps (`better-sqlite3`) match Electron's Node |
+| `validate-pack-artifact.ts` | Validate npm pack output |
+| `responses-ws-proxy.mjs` | WebSocket bridge for Codex Responses API |
+| `v1-ws-bridge.mjs` | WebSocket bridge for `/api/v1/ws` endpoint |
+| `standalone-server-ws.mjs` | Standalone WS server runner |
+| `system-info.mjs` | Print system/runtime info for support |
+| `healthcheck.mjs` | One-shot health check (used by Docker HEALTHCHECK) |
+| `uninstall.mjs` | Clean uninstall script |
+
+---
+
+## `docs/` โ Public Documentation (44 files + 4 subdirs)
+
+### Top-level guides
+
+| Doc | Purpose |
+| --------------------------- | ------------------------------------------------------------------------------------- |
+| `ARCHITECTURE.md` | High-level architecture, subsystem map, dashboard surface |
+| `CODEBASE_DOCUMENTATION.md` | Engineering reference: directories, modules, conventions |
+| `FEATURES.md` | Feature matrix with v3.8 highlights |
+| `USER_GUIDE.md` | End-user manual (setup, models, combos, CLIs, audio, etc.) |
+| `API_REFERENCE.md` | API endpoint reference with auth model |
+| `openapi.yaml` | OpenAPI 3.0 spec (121 paths) |
+| `SETUP_GUIDE.md` | Install methods (npm, npx, Docker, Electron, Termux, source) |
+| `ENVIRONMENT.md` | All env vars (~219 used in code, ~810 lines `.env.example`) |
+| `TROUBLESHOOTING.md` | Common errors + v3.8.0 known issues |
+| `RELEASE_CHECKLIST.md` | Full release flow (skills, husky, conventional commits, deploy) |
+| `COVERAGE_PLAN.md` | Coverage goals and current state |
+| `FREE_TIERS.md` | Curated free-tier providers (48+ free + 11 OAuth) |
+| `CLI-TOOLS.md` | External CLI integrations + Internal OmniRoute CLI |
+| `I18N.md` | i18n architecture, adding a language, 30 locales |
+| `UNINSTALL.md` | Clean uninstall steps |
+| `PROVIDER_REFERENCE.md` | **Auto-generated** catalog of 177 providers (regen: `npm run gen:provider-reference`) |
+
+### Subsystem deep-dives
+
+| Doc | Purpose |
+| -------------------------- | ------------------------------------------------------------------- |
+| `MCP-SERVER.md` | MCP server: 37 tools, 3 transports, ~13 scopes, REST endpoints |
+| `A2A-SERVER.md` | A2A v0.3: JSON-RPC, 5 skills, REST helpers, agent card |
+| `AGENT_PROTOCOLS_GUIDE.md` | Unified guide: A2A vs ACP vs Cloud Agents |
+| `CLOUD_AGENT.md` | Codex Cloud / Devin / Jules orchestration |
+| `SKILLS.md` | Skills framework (built-in + marketplace + SkillsSH + sandbox) |
+| `MEMORY.md` | Memory system (SQLite FTS5 + Qdrant) |
+| `EVALS.md` | Eval framework (suites, runs, rubrics) |
+| `GUARDRAILS.md` | PII masker, prompt injection, vision bridge |
+| `COMPLIANCE.md` | Audit log, retention, noLog opt-out |
+| `WEBHOOKS.md` | HMAC-signed webhook delivery |
+| `REASONING_REPLAY.md` | Hybrid memory/SQLite cache for `reasoning_content` |
+| `AUTHZ_GUIDE.md` | Authorization pipeline (`classify` โ `policies` โ `enforce`) |
+| `RESILIENCE_GUIDE.md` | Circuit breaker + cooldown + model lockout |
+| `STEALTH_GUIDE.md` | TLS fingerprinting (JA3/JA4), Claude Code CCH, MITM cert |
+| `AUTO-COMBO.md` | Auto Combo engine (9-factor scoring, 4 mode packs, virtual factory) |
+
+### Compression
+
+| Doc | Purpose |
+| ------------------------------- | ---------------------------------------- |
+| `COMPRESSION_GUIDE.md` | Overview of compression modes + roadmap |
+| `COMPRESSION_ENGINES.md` | Caveman + RTK engines, registry contract |
+| `COMPRESSION_RULES_FORMAT.md` | Caveman rule pack JSON schema |
+| `COMPRESSION_LANGUAGE_PACKS.md` | Per-language rule pack inventory |
+| `RTK_COMPRESSION.md` | RTK declarative pipeline (49 filters) |
+
+### Deployment
+
+| Doc | Purpose |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `DOCKER_GUIDE.md` | Docker build, profiles (base/cli/host/cliproxyapi), Redis sidecar |
+| `VM_DEPLOYMENT_GUIDE.md` | Generic VM/VPS deployment (Ubuntu/Debian + nginx + systemd) |
+| `FLY_IO_DEPLOYMENT_GUIDE.md` | Fly.io deployment (currently Chinese-only) |
+| `TERMUX_GUIDE.md` | Android headless via Termux |
+| `PWA_GUIDE.md` | Progressive Web App install + service worker |
+| `ELECTRON_GUIDE.md` | Desktop app build + sign + distribute |
+| `TUNNELS_GUIDE.md` | Cloudflared + ngrok + Tailscale Funnel |
+| `PROXY_GUIDE.md` | 4-level outbound proxy + 1proxy marketplace |
+
+### Subdirectories
+
+| Subdir | Purpose |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| `docs/archive/` | Archived/historical docs (e.g., `RFC-AUTO-ASSESSMENT-DRAFT.md` โ superseded by EVALS) |
+| `docs/i18n/` | Localized doc translations (~40 locales) |
+| `docs/screenshots/` | Image assets for guides |
+| `docs/superpowers/plans/` | Implementation plans (generated by `superpowers:writing-plans` skill) |
+
+---
+
+## `tests/` โ Test Suites
+
+| Subdir | Type | Runner |
+| ---------------------- | --------------------------------------- | --------------------------------------- |
+| `tests/unit/` | Unit tests (~500 files, fastest) | Node native test runner |
+| `tests/integration/` | Multi-module + DB integration tests | Node native test runner (concurrency 1) |
+| `tests/e2e/` | UI + workflow E2E | Playwright |
+| `tests/protocols-e2e/` | MCP + A2A real-client E2E | Custom protocol clients |
+| `tests/ecosystem/` | Provider integration (network-touching) | Node native test runner |
+
+---
+
+## `public/` โ Static Assets
+
+| Path | Purpose |
+| ------------------- | ---------------------------------------------------------------- |
+| `public/` (root) | Favicons, robots.txt, manifest, service worker, marketing images |
+| `public/providers/` | Provider logo PNG/SVG (used in dashboard) |
+
+---
+
+## `config/` โ Static Configs
+
+Shipped configuration templates and sample files (referenced by setup wizard).
+
+---
+
+## `.github/` โ GitHub Integration
+
+| Path | Purpose |
+| ---------------------------------- | -------------------------------------------------------------- |
+| `.github/workflows/` | GitHub Actions CI/CD workflows (lint, test, coverage, release) |
+| `.github/ISSUE_TEMPLATE/` | Bug/feature issue templates |
+| `.github/PULL_REQUEST_TEMPLATE.md` | PR template |
+| `.github/dependabot.yml` | Dependency update config |
+
+---
+
+## `.husky/` โ Git Hooks
+
+| File | Purpose |
+| ------------ | ----------------------------------------------------------------- |
+| `pre-commit` | Runs `lint-staged + check-docs-sync + check:any-budget:t11` |
+| `pre-push` | Currently disabled (commented). Run `npm run test:unit` manually. |
+| `_/` | Husky internals |
+
+---
+
+## `.claude/` โ Claude Code Slash Commands
+
+| File | Purpose |
+| ----------------------------------------------------------------- | -------------------------------------------------- |
+| `commands/version-bump-cc.md` | `/version-bump-cc` โ bump version + auto-changelog |
+| `commands/generate-release-cc.md` | `/generate-release-cc` โ full release workflow |
+| `commands/deploy-vps-{local,akamai,both}-cc.md` | Deploy to VPS |
+| `commands/capture-release-evidences-cc.md` | Browser-record new features as WebP |
+| `commands/review-{prs,discussions}-cc.md` | Triage GitHub PRs/discussions |
+| `commands/{issue-triage,resolve-issues,implement-features}-cc.md` | Issue workflows |
+| `settings.local.json` | Per-project Claude Code settings |
+
+---
+
+## `.agents/` โ Generic Agent Workflows (Codex / Cursor / etc.)
+
+| Path | Purpose |
+| ------------------------ | ------------------------------------------------------- |
+| `workflows/*-ag.md` | 11 workflow definitions (mirror of `.claude/commands/`) |
+| `skills//SKILL.md` | 9 skill definitions with Codex Execution Notes |
+
+> **Note:** Workflows and commands are currently identical byte-by-byte. If `.agents/` is meant to target a different agent runtime (Codex), the variants need to diverge meaningfully.
+
+---
+
+## `_ideia/`, `_mono_repo/`, `_references/`, `_tasks/` โ Out-of-tree
+
+These underscore-prefixed directories hold non-shipping content:
+
+- **`_ideia/`** โ design notes (defer / notfit / viable categories)
+- **`_mono_repo/`** โ historic subprojects (omnirouteCloud, omnirouteSite, vscode-extension)
+- **`_references/`** โ read-only clones of related OSS projects (LiteLLM, 9router, ClawRouter, CLIProxyAPI, modelrelay, new-api, etc.) for cross-reference during development
+- **`_tasks/`** โ per-release task tracking files (informal)
+
+Not included in `npm pack` output. See `.npmignore`.
+
+---
+
+## Generated / Gitignored
+
+| Path | Purpose |
+| ---------------------- | ----------------------------- |
+| `node_modules/` | npm dependencies |
+| `.next/` | Next.js build output |
+| `coverage/` | c8 coverage reports |
+| `logs/` | Runtime logs |
+| `package/` | npm pack staging |
+| `.playwright-mcp/` | Playwright MCP test artifacts |
+| `.issues/` | Local issue cache |
+| `tsconfig.tsbuildinfo` | TS incremental cache |
+
+---
+
+## Navigation tips
+
+- **New contributor?** Read `CONTRIBUTING.md` โ `CLAUDE.md` โ `docs/ARCHITECTURE.md` โ `docs/CODEBASE_DOCUMENTATION.md`.
+- **Adding a provider?** Follow `docs/ARCHITECTURE.md ยง Adding a New Provider` + cross-check `docs/PROVIDER_REFERENCE.md`.
+- **Adding a route?** `docs/ARCHITECTURE.md ยง Adding a New API Route` + `src/shared/validation/schemas.ts`.
+- **Adding an MCP tool?** `docs/MCP-SERVER.md ยง Adding a Tool`.
+- **Adding an A2A skill?** `docs/A2A-SERVER.md ยง Adding a New Skill`.
+- **Running locally?** `docs/SETUP_GUIDE.md`.
+- **Deploying?** `docs/DOCKER_GUIDE.md` / `docs/VM_DEPLOYMENT_GUIDE.md` / `docs/FLY_IO_DEPLOYMENT_GUIDE.md`.
+- **Releasing?** `docs/RELEASE_CHECKLIST.md` (and `/generate-release-cc` Claude Code skill).
-ff6600?style=for-the-badge&labelColor=1a1a2e&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyTDIgNy41bDEwIDUuNSAxMC01LjVMMTIgMnpNMiAxNy41bDEwIDUuNSAxMC01LjVMMTIgMTIgMiAxNy41eiIvPjwvc3ZnPg==){kind=icon}
-
-
-๐ฅ Limited offer: Sign up at AgentRouter and get $100 in free AI credits Access GPT-5, Claude, Gemini, DeepSeek & 100+ models. No credit card required. Claim your credits โ
-
-
-
- 
- 
- 
